Provides a read-only GitHub interface for AI agents with proxy support, ETag caching, and automatic credential reuse for reliable repository access.
Also known as KurvCygnus/github-fetcher, @kurvcygnus/github-fetcher
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 952
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is github-fetcher MCP?
github-fetcher provides a read-only GitHub interface for AI agents with proxy support, ETag caching, and automatic credential reuse for reliable repository access.
Summary generated from the project's README
About github-fetcher MCP server
Providing a read-only gateway to GitHub repositories is what github-fetcher enables for AI coding agents. It offers 32 specialized tools via stdio to inspect files, commits, issues, pull requests, and repository health without the risk of accidental modifications. This server is designed to be lightweight and reliable, making it ideal for developers using clients like Claude Desktop, Cursor, or VS Code who need to feed repository context into their AI workflows.
To ensure stability, the server automatically reuses credentials from your existing git credential store or accepts a GITHUB_TOKEN. It features built-in proxy support to navigate restrictive networks and uses an ETag disk cache to prevent repeated requests from exhausting your GitHub API quota. By caching successful responses locally, it minimizes network traffic and respects rate limits, even providing exact reset times when limits are reached. This makes it a specialized alternative to general-purpose servers when the primary goal is safe, efficient data retrieval.
What you can do with it
- 1Monitor repository healthDevelopers can task an agent with checking the current activity and health metrics of a project.
- 2Efficiently manage API quotasThe server prevents redundant network calls by storing previously fetched data on your local disk.
- 3Navigate restricted network environmentsUsers in regions with DNS poisoning can route their GitHub requests through a configured proxy.
Written from the project's README. Every use case is checked against a quote from it.
How to install github-fetcher MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall github-fetcher MCP in Claude Code
$ claude mcp add github-fetcher -- npx -y @kurvcygnus/github-fetcherInstall github-fetcher MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"github-fetcher": {
"command": "npx",
"args": [
"-y",
"@kurvcygnus/github-fetcher"
]
}
}
}Install github-fetcher MCP in VS Code
.vscode/mcp.json
{
"servers": {
"github-fetcher": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@kurvcygnus/github-fetcher"
]
}
}
}Install github-fetcher MCP in VS Code CLI
$ code --add-mcp '{"name":"github-fetcher","type":"stdio","command":"npx","args":["-y","@kurvcygnus/github-fetcher"]}'Install github-fetcher MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"github-fetcher": {
"command": "npx",
"args": [
"-y",
"@kurvcygnus/github-fetcher"
]
}
}
}Install github-fetcher MCP in Codex
$ codex mcp add github-fetcher -- npx -y @kurvcygnus/github-fetcherInstall github-fetcher MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.github-fetcher] command = "npx" args = ["-y", "@kurvcygnus/github-fetcher"]
Install github-fetcher MCP in Gemini CLI
$ gemini mcp add -s user github-fetcher npx -- -y @kurvcygnus/github-fetcherInstall github-fetcher MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"github-fetcher": {
"command": "npx",
"args": [
"-y",
"@kurvcygnus/github-fetcher"
]
}
}
}Configuration
GITHUB_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablekurvcygnus/github-fetcher is public and reachablegithub.com/kurvcygnus/github-fetcher ↗Pass
- Package names this repository as its source@kurvcygnus/github-fetcher names kurvcygnus/github-fetcher as sourcenpmjs.com/package/@kurvcygnus/github-fetcher ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @kurvcygnus/github-fetchernpmjs.com/package/@kurvcygnus/github-fetcher/v/0.3.0#provena ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/kurvcygnus/github-fetcher ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @kurvcygnus/github-fetcherPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@kurvcygnus/github-fetcher
AI coding agents spend much of their time reading GitHub, and this server makes that read path safe, cheap, and reliable. @kurvcygnus/github-fetcher is a read-only GitHub MCP server: it exposes 32 tools over stdio for reading repositories, users, files, commits, issues, pull requests, releases, repository health and activity, side-by-side repository and ref comparison, its own capability index and diagnostics, Actions, and search results through the GitHub REST API. It reuses credentials you already have, routes around unreliable networks, caches responses on disk, and cannot modify anything.
Built for mainland China networks
GitHub's anonymous REST quota is 60 requests per hour per egress IP, shared by every tool on the machine. raw.githubusercontent.com is frequently DNS-poisoned, and bare HTTP clients that omit User-Agent get a 403. This server is built around those failures:
- Reuses the token already in your git credential store;
GITHUB_TOKEN/GH_TOKENoverride it. - Tries
api.github.comdirectly first, then your proxy. File reads use the contents API for metadata and inline content, then fetchraw.githubusercontent.comthrough the proxy when GitHub omits the inline body. - Retries transport failures twice per route, waits out rate-limit windows up to 15 seconds, and reports the exact reset time for longer ones.
- Caches successful responses on disk with ETag revalidation, so repeated reads do not spend quota.
If you are outside mainland China, the same defaults still work; set GITHUB_PROXY_MODE=direct to skip proxy attempts entirely.
The problem
Agents read GitHub constantly (trees, files, issues, pull requests, CI), and direct access fails in ways that waste everyone's time:
- Anonymous REST access is capped at 60 requests per hour per IP, a budget shared by every tool on the machine.
- GitHub answers requests without a
User-Agentheader with 403, so bare scripts fail for a reason that is hard to spot. - On networks where
raw.githubusercontent.comis DNS-poisoned (common in mainland China), raw file fetches fail outright. - Handing agents a write-scoped token for read-only work is a needless risk.
- Without a shared cache, every tool re-fetches the same content.
What you get
- 32 read-only MCP tools over stdio: repositories, users, trees, files, commits, branches, issues, pull requests, releases, repository health and activity, side-by-side repository and ref comparison, user profiles, stars, and events, a capability discovery index with a self-diagnostic, search, Actions runs, and a generic read-only GET escape hatch.
- Token reuse from the git credential store: the server reads what your git credential helper already holds (for example the GitHub CLI or Git Credential Manager), so no new secrets land on disk.
GITHUB_TOKENtakes precedence, and with no token at all it falls back to anonymous access (60 requests per hour). - Proxy routing built for hostile networks: in
automode API requests go direct-first whileraw.githubusercontent.comrequests go proxy-first, withalwaysanddirectoverrides. Proxy candidates are tried in order:GITHUB_PROXY,HTTPS_PROXY,HTTP_PROXY, then your git proxy config. - An ETag disk cache that survives restarts: entries inside their TTL are served locally, expired entries are revalidated cheaply with
If-None-Match/If-Modified-Since, and a 304 answer reuses the stored body instead of downloading it again. - Rate-limit handling: short windows (up to 15 seconds) are waited out once automatically, and long ones are reported with the exact reset time.
- Client setup built in:
github-fetcher initwrites the MCP entry for eight clients and backs up every file it edits;github-fetcher removeundoes it.
Comparison with the official server
The official github/github-mcp-server is the right choice when you need a general-purpose GitHub MCP server with write tools or remote hosting. This project makes a narrower trade-off:
| Capability | GitHub Fetcher | Official github-mcp-server |
|---|---|---|
| Always read-only | Yes | Read-only mode is opt-in; write tools are available |
| Local stdio | Yes | Yes |
| Remote hosted option | No | Yes |
| Auth | Reuses git credential; GITHUB_TOKEN/GH_TOKEN |
PAT, OAuth, or GitHub App |
| Raw/proxy fallback for China | Yes | No China-specific routing |
| ETag disk cache | Yes | No built-in ETag cache |
Official-server facts were checked against its README on 2026-11-01.
Quick start
The fastest path is one command:
npx -y @kurvcygnus/github-fetcher@latest init
init detects the supported clients, reuses an existing entry that already points at this package, and backs up every file it changes. The manual entries below are the reference form.
Add the matching entry to your client's MCP configuration.
OpenCode:
{
"mcp": {
"github": {
"type": "local",
"command": ["npx", "-y", "@kurvcygnus/github-fetcher@latest"],
"enabled": true
}
}
}
Claude Desktop, in claude_desktop_config.json:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@kurvcygnus/github-fetcher@latest"],
"env": { "GITHUB_TOKEN": "ghp_your_token" }
}
}
}
Cursor, in .cursor/mcp.json:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@kurvcygnus/github-fetcher@latest"]
}
}
}
VS Code, in .vscode/mcp.json:
{
"servers": {
"github": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@kurvcygnus/github-fetcher@latest"]
}
}
}
All four clients run the same command; add an env block with GITHUB_TOKEN where the client supports one, or export the variable in the shell the client launches from.
CLI
Every tool is also a subcommand of the same binary - useful for shell pipelines and for checking data without an agent in the loop.
After a global install (npm i -g @kurvcygnus/github-fetcher), the short alias ghf is registered alongside github-fetcher, so ghf releases anomalyco/opencode --per-page 5 works too.
github-fetcher releases anomalyco/opencode --per-page 5 | jq -r ".items[].tag_name"
github-fetcher health anthropics/claude-code --window-days 30 --pretty
github-fetcher file KurvCygnus/github-fetcher README.md
- Bare
github-fetcher(orserve) starts the MCP stdio server; a subcommand runs the CLI. - Output is compact JSON on stdout (
--prettyfor humans); errors are JSON on stderr with exit codes: 2 usage, 3 rate limited, 4 auth, 5 not found, 6 network, 7 upstream. --version(-v) prints the package version;--helplists subcommands, andgithub-fetcher <subcommand> --helpshows one tool's flags.initandremovemanage MCP client configuration instead of querying GitHub; they are described below.
init
github-fetcher init adds the github entry to your MCP client configuration. On a terminal it opens a selection menu (Space toggles, a toggles all, Enter confirms, Esc cancels; clients whose configuration already exists start selected). Scripts use flags instead:
github-fetcher init --dry-run
github-fetcher init --client opencode,cursor
github-fetcher init --client opencode --name github
--client id,idnames clients (comma-separated);--allsweeps every adapter;--dry-runreportswould-create,would-update, orwould-skipand leaves files alone;--namesets the entry name (defaultgithub).--dry-runwith neither--clientnor--allstill sweeps every adapter, so undetected clients reportnot-installedinstead ofwould-create.- By default,
initreuses an existing entry whosecommandorargsalready point at this package, even under a legacy key such asgithub-fetcher, and updates that entry instead of adding a twin.--namedisables resolution and forces that exact key. A key that already belongs to another server is never overwritten: when no owned legacy key exists, the client reportsskipped, and--nameselects another key. - A missing configuration is created only for a client selected explicitly (
--client, or a pick in the menu); an undetected client that was not selected reportsnot-installedand nothing is written for it.--allalone covers every detected client and reports the rest asnot-installed. - Every change to an existing file is preceded by a backup next to it as
<path>.bak.<timestamp>; the backup completes before the target changes, and a rerun in the same second gets a numeric suffix instead of overwriting the earlier backup. - stdout carries one JSON array with one object per client (
created,updated,skipped,not-installed,would-*,error), including the resolved entryname; the resolved auth mode (tokenoranonymous) is reported on stderr. Cancelling the menu printscancelledand exits 0.
Supported clients: opencode, claude-desktop, claude-code, cursor, vscode, gemini, windsurf, codex.
remove
github-fetcher remove deletes the entry again. Without flags it offers only clients whose configuration already contains the entry, all preselected; --client id,id and --all skip the menu, and --name selects which entry to remove. A bare remove needs an interactive terminal for that menu and exits 2 when stdin is not a TTY; pass --client or --all to run unattended.
- Only existing entries are touched: a client with no configuration reports
not-installed, a client whose configuration lacks the entry reportsskipped, and neither file is rewritten. A key that belongs to another server is never removed; it reportsskippedwith a message. - The current file is backed up before the removal is written, with the same
<path>.bak.<timestamp>naming asinit. - Removing the last entry deletes a configuration file that would become empty; the result reports
deleted: true, and the backup remains as the recovery copy. A top-level key or a sibling entry keeps the file. - ZCode is deliberately unsupported: it is not an adapter, so
initnever offers it andremovenever reads or writes its configuration.
Limitations
- Read-only by design: no writes, no GraphQL, no clone or archive tools.
- 32 tools, not a complete GitHub API client; use
github_api_getfor read-only REST endpoints the dedicated tools do not cover. - Anonymous access is 60 requests per hour; code search requires a token.
- No proxy is bundled; bring your own HTTP(S) proxy.
- The cache stores response bodies on disk; do not use it on a shared account if that is unacceptable.
Security model
- Read-only by construction: the server issues only GET requests; GraphQL and write operations are not supported, and
github_api_getaccepts arbitrary read-only GET paths, host fixed to api.github.com. - Only two hosts are ever contacted:
api.github.comfor API calls andraw.githubusercontent.comfor raw bytes. - Redirects are confined to GitHub origins: a redirect that leaves the original host is refused.
- Tokens appear only in the Authorization header, never in logs, errors, tool output, or the cache; cache keys use a SHA-256 hash of the token.
- Cache files are written with 0600 permissions (best effort) under the user's own cache directory.
- Identity is private by default:
github_rate_limitreports quota only. SettingGITHUB_MCP_EXPOSE_IDENTITYopts in toauthenticated_asandscopes; the token and its fingerprint are never returned either way.
How it works
Every tool call becomes one GET against the GitHub REST API. A cache layer sits in front of it: entries younger than the endpoint TTL are served locally, expired entries are revalidated with ETag validators, and only successful responses are cached, so a not-found answer is never cached and surfaces as not_found every time. Every API-reading tool except github_rate_limit accepts a fresh option that bypasses the cache for a single request; github_api_get responses are cached like every other tool; github_capabilities takes no input. Every network-backed response ends with meta: {cache, age_s, quota}. Below the cache, the HTTP layer picks a route per request, retries transport failures, waits out short rate-limit windows, and refreshes a rejected token once before failing.
stdio MCP → tool registry → GithubClient (ETag cache) → HttpClient (routing, proxy, retries) → GitHub REST
Configuration
| Variable | Default | Purpose |
|---|---|---|
GITHUB_TOKEN |
unset | GitHub token, tried first. |
GH_TOKEN |
unset | Fallback token, used when GITHUB_TOKEN is not set. |
GITHUB_PROXY |
unset | Dedicated proxy URL (http:// or https://), tried before the general proxy variables. |
GITHUB_PROXY_MODE |
auto |
Proxy routing mode: auto, always, or direct. |
HTTPS_PROXY |
unset | General HTTPS proxy fallback. |
HTTP_PROXY |
unset | General HTTP proxy fallback, tried after HTTPS_PROXY. |
GITHUB_CACHE |
disk |
Cache backend: disk, memory, or off. |
GITHUB_CACHE_DIR |
platform cache directory | Overrides the disk cache location. |
GITHUB_MCP_TIMEOUT_MS |
30000 |
Per-request timeout in milliseconds. |
GITHUB_MCP_MAX_FILE_BYTES |
262144 |
Maximum response text in UTF-8 bytes before truncation (per-call max_bytes caps it further). |
GITHUB_MCP_EXPOSE_IDENTITY |
unset | Opt-in: 1/true/yes/on makes github_rate_limit and github_doctor add authenticated_as and scopes; every other value keeps identity off. |
GITHUB_MCP_LOG |
error |
Parsed and validated; currently unused — warnings always go to stderr regardless of level. |
Invalid values are ignored with a warning on stderr and the default applies.
Tool capabilities at a glance
Agents receive the full input schema for every tool via tools/list; github_capabilities carries the same facts as derived per-tool input rows (name, optionality, description), so the index and the schema cannot drift apart. The groups match the index returned by github_capabilities.
- Meta:
github_capabilities(one-line summaries withEnvelope:tags, plus per-tool derivedinputrows and an input signature),github_rate_limit(projects core and search by default;all: trueexpands to every bucket; identity opt-in viaGITHUB_MCP_EXPOSE_IDENTITY),github_api_get(arbitrary read-only GET on api.github.com; a query string inpathand scalarqueryvalues;paginationcarries the Link-header URLs; GraphQL unsupported),github_doctor(one-screen health check: token presence, opt-in identity, proxy reachability, cache state, and quota) - Repository:
github_repo(reportsvisibility),github_repos(batch lookup of up to 20 repositories with per-item ok/error),github_compare_refs(ahead/behind counts, total commits, and up to 100 changed files with patches capped at 4000 characters),github_branches,github_languages(bytes per language, sorted descending),github_contributors(login, account type, and contribution count),github_repo_activity(pull, issue, commit, contributor, and release counts for a window, from core endpoints only, with truncation flags) - User:
github_user(one profile: name, type, bio, company, location, blog, and follower counts),github_user_repos(a user's repositories with the house projection;typedefaults toowner),github_user_starred(starred repositories with thestarred_attime),github_user_events(public events only) - Files:
github_tree(returns at mostmax_entriesentries, default 1000, withtotal_entries, a typesummary, andapi_truncated; a timed-out recursive listing degrades to top-level entries withdegraded: true;summary_only: truedropsentriesand returnstotal_bytesplustop_dirsinstead),github_file(supports 1-basedstart_line/end_lineranges and a per-callmax_bytesbudget) - History:
github_commits - Collaboration:
github_issue,github_issues(acceptssince, an ISO 8601 timestamp, to filter by update time),github_pr,github_prs - Releases:
github_release(latest or tagged release with assets and download URLs; assets carrydigestwhere GitHub provides one),github_releases - Snapshot:
github_repo_health,github_compare_repos(throttled breadth comparison of up to 20 repositories in one call) - Search:
github_search_repos(reportsprivate,visibility,topics, andlicenseper item;public_onlydefaults totrue— passfalseto include private items — filters client-side, and reportsfiltered_count, whiletotal_countstays GitHub's unfiltered total),github_search_code(token required),github_search_issues - Actions:
github_workflows,github_workflow_runs,github_workflow_run
Troubleshooting
| Symptom | Meaning | What to do |
|---|---|---|
403/429 with rate_limited |
The quota for this credential is exhausted | Call github_rate_limit and wait for the reset it reports |
| DNS or connection failures for raw or API hosts | The path to GitHub is unreliable on this network | Set GITHUB_PROXY or HTTPS_PROXY |
auth_missing |
The endpoint needs a token; github_search_code requires one |
Set GITHUB_TOKEN or GH_TOKEN |
not_found |
The repository, ref, path, or release tag does not exist, or is private | Check owner/name and the ref |
| TLS errors | TLS interception (corporate MITM) or a broken proxy path | Point GITHUB_PROXY or HTTPS_PROXY at a working proxy, or try GITHUB_PROXY_MODE=direct |
Development
npm test: run the test suitenpm run typecheck: strict TypeScript checknpm run build: production buildnpm run smoke: spawns the built server over stdio and asserts that all 32 tools are listedGITHUB_SMOKE=1 npm test: runs the suite withGITHUB_SMOKEset; the variable is reserved and currently unused
License
MIT. Copyright (c) 2026 Kurv Cygnus. See LICENSE.
github-fetcher MCP questions
How do I add github-fetcher MCP to Claude Code?
Run claude mcp add github-fetcher -- npx -y @kurvcygnus/github-fetcher in your terminal. Add --scope user to make it available in every project.
How do I add github-fetcher MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is this server capable of making changes to my GitHub repositories?
No, the server is read-only by design and only issues GET requests to prevent accidental modifications.
How does the server handle authentication?
It reuses tokens from your existing git credential store, though you can override this using GITHUB_TOKEN or GH_TOKEN environment variables.
Does the server help with GitHub API rate limits?
Yes, it uses an ETag disk cache to avoid re-fetching content and includes automatic retries and rate-limit window handling.