github-fetcher
A read-only GitHub MCP server exposing 41 tools over stdio for inspecting GitHub without ever modifying anything.
Repositories — metadata (visibility, stars, forks, topics, license), batch lookup of up to 20 repos, and side-by-side breadth comparison
Files & trees — list trees (recursive or summary-only), read files with line ranges and byte budgets, fetch resolved READMEs, batch-read up to 10 paths, and regex-grep a file with context lines
History — list commits (filtered by path, author, date range) and read single-commit detail with changed files and bounded patches
Collaboration — read issues and pull requests individually (optionally with comments or changed files) and list them with state/label/sort/since filters
Releases & Actions — latest or tagged releases with assets and download URLs; workflows, workflow runs, and single-run detail including jobs and steps
Users — profiles, repos (fork/star filters, star ranking), stars with timestamps, public events, and a one-call user health audit
Search — repositories, code (token required), issues/PRs, users, plus an approximated trending view with star deltas
Health & activity — one-call repo snapshot with windowed issue counts and labels, plus activity metrics (PR merge times, commits, contributors, releases)
Ref comparison — compare two refs with ahead/behind counts and up to 100 changed files
Meta & diagnostics — capability index, rate-limit projection, server doctor (token, proxy, cache, quota), ref pinning for a session, and a generic read-only
github_api_getescape hatchOperational extras — token reuse from git credentials, proxy routing for hostile networks, disk ETag caching with
freshbypass, and CLI subcommands mirroring every tool
Provides read-only access to GitHub through 18 MCP tools for repositories, trees, files, commits, branches, issues, pull requests, releases, Actions workflows and runs, search, rate limits, and generic read-only GitHub REST API GET requests. It uses GitHub tokens from environment or git credential helpers, caches responses with ETags, and supports proxy routing for unreliable networks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@github-fetcher read the README from kurvcygnus/github-fetcher"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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 41 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.
Related MCP server: GitHub Analyzer MCP Server
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
41 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; | 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 initinit 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.mdBare
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.
41 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. Tool results travel a single channel: the response carries structuredContent only, and the content array stays empty, so legacy text-only clients see an empty payload instead of a duplicated text rendering. 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. Paths reaching the API client are validated with the same rules as the raw path. Every network-backed response ends with meta: {cache, age_s, quota}; on a cache hit, quota reflects the fetch that produced the cached body, and age_s tells you how old that body is. github_pin_ref pins a repository to a commit sha in server memory: file, tree, and commit reads without an explicit ref anchor to that pin for the rest of the session, and the pin is lost on restart. github_file_grep is cache-first: a warm cache answers with zero upstream calls and a miss costs one. 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 |
| unset | GitHub token, tried first. |
| unset | Fallback token, used when |
| unset | Dedicated proxy URL ( |
|
| Proxy routing mode: |
| unset | General HTTPS proxy fallback. |
| unset | General HTTP proxy fallback, tried after |
|
| Cache backend: |
| platform cache directory | Overrides the disk cache location. |
|
| Per-request timeout in milliseconds. |
|
| Time budget in milliseconds for |
|
| Maximum response text in UTF-8 bytes before truncation (per-call |
| unset | Opt-in: |
|
| 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;grouprestricts the index to one group),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),github_pin_ref(pins a repository to a commit sha for the session: file, tree, and commit reads without an explicitrefanchor to the pin, which lives in server memory and is lost on restart)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),github_stargazers(stargazers with thestarred_attime via the star+json media type; pages run oldest-first, so paged calls build a star timeline)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; forks are dropped by default andinclude_forks: truekeeps them;min_starssets a star floor;sort: starsgathers up to 10 pages of 100 and ranks by stars descending, reportinggather_truncatedwhen the cap stopped the gather),github_user_starred(starred repositories with thestarred_attime),github_user_events(public events only),github_user_health(one-call audit: original vs fork split withfork_share, total stars, top repositories by stars, language distribution, and 90-day push activity; 2-11 core calls; detail metrics exclude forks unlessinclude_forks: true)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),github_readme(fetches the repository's README through GitHub's readme endpoint, which resolves the default naming variant; usegithub_filefor a specific path),github_file_grep(regex search in one file with 1-based line and column,context_linesdefaulting to 2, andmax_matchesdefaulting to 50 withmatches_truncated; cache-first, so a warm cache costs zero upstream calls; matching runs in a worker thread with a 2000 ms time budget (GITHUB_MCP_GREP_TIMEOUT_MS); overruns degrade tomatches_truncatedinstead of blocking the session; binary or non-UTF-8 files are rejected),github_files(batch read of up to 10 paths from one repository, one core call per uncached path, per-item ok/error so one missing path never rejects the call);github_fileandgithub_tree404 misses carry a recoveryhint— branch/tag advice for a ref miss, cached sibling names for a path miss — built from the local cache with no extra upstream callsHistory:
github_commits(max_message_charstruncates each commit message),github_commit(single-commit detail: message, author, additions/deletions, and the changed files with bounded patches; up to 100 files withfiles_truncatedand patch text capped at 4000 characters; 1 core call)Collaboration:
github_issue,github_issues(acceptssince, an ISO 8601 timestamp, to filter by update time),github_pr,github_prsReleases:
github_release(latest or tagged release with assets and download URLs; assets carrydigestwhere GitHub provides one),github_releasesSnapshot:
github_repo_health,github_compare_repos(throttled breadth comparison of up to 20 repositories in one call)Search:
github_search_repos(reportsprivate,visibility,topics,license,created_at, andpushed_atper 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,github_search_users(user search by GitHub query syntax —location:,language:,followers:>=N,repositories:>=Nqualifiers; lean profiles, with detail ingithub_user),github_trending(computed approximation from GitHub search, NOT GitHub's trending page: a rising lens of repositories created inside the window and an active lens of repositories pushed inside it, both star-sorted; each observation is snapshotted, so repeated calls with the same lens gainstars_gainedagainst the prior; 2 search calls)Actions:
github_workflows,github_workflow_runs,github_workflow_run
Troubleshooting
Symptom | Meaning | What to do |
403/429 with | The quota for this credential is exhausted | Call |
DNS or connection failures for raw or API hosts | The path to GitHub is unreliable on this network | Set |
| The endpoint needs a token; | Set |
| The repository, ref, path, or release tag does not exist, or is private | Check |
TLS errors | TLS interception (corporate MITM) or a broken proxy path | Point |
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 41 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.
Available Tools
41 toolsgithub_api_getGitHub API GETARead-onlyIdempotent
Escape hatch for read-only GitHub REST GET requests that the dedicated tools do not cover. The host is fixed to api.github.com; GraphQL and writes are not supported. Returns {status, content_type, body, truncated, pagination, meta?}.
Inputs: path (required), fresh, query.
github_branchesGitHub branchesBRead-onlyIdempotent
List branches with their head sha and protection state. Returns {items[{name, sha, protected}], page, per_page, has_more, next_page}.
Inputs: repo (required), page, fresh, per_page.
github_capabilitiesGitHub capabilitiesARead-onlyIdempotent
Task-grouped index of every tool in this server. Call this first when unsure which tool fits a job; costs nothing. Returns {total, groups[{group, tools[{name, summary, signature, input}]}]}.
Inputs: group.
github_commitGitHub commitARead-onlyIdempotent
Read one commit: message, author, additions/deletions, and the changed files with bounded patches. github_commits lists commits; this reads one in full. Costs 1 core call. Returns {repo, sha, author, date, message, additions, deletions, files, files_truncated, meta}.
Inputs: repo (required), ref, fresh.
github_commitsGitHub commitsARead-onlyIdempotent
List commits on a ref, optionally filtered by path, author, or date range. Returns short sha, message, author, and date; max_message_chars truncates each message. Returns {items[{sha, short_sha, message, author{name, email, login}, date, url}], page, per_page, has_more, next_page}.
Inputs: repo (required), ref, page, path, +6 more.
github_compare_refsGitHub ref comparisonARead-onlyIdempotent
Compares two refs in one repository, one core call: ahead/behind counts, total commits, and the first 100 changed files with each patch capped at 4000 characters. Unknown refs surface the standard 404 error. Returns {status, ahead_by, behind_by, total_commits, files[{filename, status, additions, deletions, patch}], files_truncated?}.
Inputs: base (required), head (required), repo (required), fresh.
github_compare_reposGitHub repository comparisonARead-onlyIdempotent
Throttled multi-repo breadth comparison: stars, open issue/PR counts, window closed count, and latest release for up to 20 repositories in one call. About 5 upstream calls per repo, roughly 10 repos/minute (search quota). Label-level detail lives in github_repo_health. Returns {window_days, repos[{repo, stars, has_issues, has_discussions, open_issues, open_prs, search_unavailable, window, latest_release} or {repo, error}], elapsed_ms}.
Inputs: repos (required), fresh, window_days.
github_contributorsGitHub repository contributorsARead-onlyIdempotent
List a repository's contributors with login, account type, and contribution count; anonymous contributors are never included. Costs 1 core call. Returns {items[{login, type, contributions}], page, per_page, has_more, next_page}.
Inputs: repo (required), page, fresh, per_page.
github_doctorGitHub health checkARead-onlyIdempotent
One-screen health check of this server's own wiring: token presence, opt-in identity, proxy mode with a TCP reachability probe of the resolved proxy, local cache state, and current quota. Costs 1 core call. Returns {token{present}, identity?{authenticated_as, scopes}, proxy{mode, url, reachable}, cache{mode, dir, entries, bytes}, quota{core{limit, remaining, reset}, search{limit, remaining, reset}}, meta{cache}}.
Inputs: no named parameters.
github_fileGitHub fileARead-onlyIdempotent
Read one file at a ref. Returns UTF-8 text when possible, never binary bytes, and reports sha, size, and truncation. Returns {repo, path, ref, sha, size, encoding, content, binary, truncated, start_line, end_line, total_lines}.
Inputs: path (required), repo (required), ref, fresh, +3 more.
github_file_grepGitHub file grepARead-onlyIdempotent
Search a single file's text with a regular expression and get line numbers with context. Cache-first: a warm cache costs zero upstream calls; a miss costs 1 core call. Use github_search_code for repo-wide or cross-repo search (30 requests/minute, GitHub index lag). Matching runs in a worker thread with a 2000 ms (default; GITHUB_MCP_GREP_TIMEOUT_MS) time budget; overruns degrade to matches_truncated instead of blocking the session. Returns {repo, path, ref, pattern, total_lines, matches, matches_truncated, meta}; an overrun returns no matches and carries hint instead.
Inputs: path (required), repo (required), pattern (required), ref, +3 more.
github_filesGitHub file batchARead-onlyIdempotent
Batch file read: fetches up to 10 paths per call from one repository concurrently, one core call per uncached path, zero for cache hits, and reports per-item success and failure so one missing or malformed path never rejects the call. Returns {results[{path, ok, data{path, sha, size, encoding, content, binary, truncated}} or {path, ok, error{code, message}}], elapsed_ms, meta}.
Inputs: repo (required), paths (required), ref, fresh.
github_issueGitHub issueARead-onlyIdempotent
Read one issue, or pull request, with labels and assignees. Set include_comments=true to fetch the latest comments in chronological order; comment_limit caps how many (default 20) and max_comment_chars truncates each body. Returns issue fields {number, title, state, author, labels, assignees, body, created_at, updated_at, closed_at, comments_count, html_url}; adds {comments[{author, body, created_at}], comments_truncated} when include_comments is true.
Inputs: repo (required), number (required), fresh, comment_limit, +2 more.
github_issuesGitHub issuesARead-onlyIdempotent
List issues in a repository with state, label, sort, direction, and since filters. Defaults to issues only; set type to "all" to include pull requests or "pr" for pull requests alone. For aggregate counts over a time window, use github_repo_health instead of paging. Returns {items[{number, title, state, type, author, labels, created_at, updated_at, html_url, comments_count}], page, per_page, has_more, next_page}.
Inputs: repo (required), page, sort, type, +6 more.
github_languagesGitHub repository languagesARead-onlyIdempotent
Read a repository's language breakdown as bytes per language, sorted by bytes descending; byte counts come from GitHub's language statistics, so they measure code bytes rather than counting file extensions. Costs 1 core call. Returns {languages, total_bytes}.
Inputs: repo (required), fresh.
github_pin_refGitHub pin refARead-onlyIdempotent
Pin a repository to a commit for the session: file, tree, and commit reads without an explicit ref anchor to this sha, keeping line-number references internally consistent across a session. The pin lives in server memory and is lost on restart. Costs 1 core call (2 for a default-branch pin; 0 when unpinning or passing a full sha). Returns {repo, ref, sha, pinned}; after an unpin the answer carries only repo and pinned (false).
Inputs: repo (required), ref, unpin.
github_prGitHub pull requestARead-onlyIdempotent
Read one pull request with branches, stats, mergeability, and optional changed files. Set include_files=true to fetch up to 100 files with patches. Returns PR fields {number, title, state, draft, merged, author, base, head, body, additions, deletions, changed_files, mergeable, created_at, updated_at, merged_at, html_url}; adds {files[{filename, status, additions, deletions, changes, patch}], files_truncated} when include_files is true.
Inputs: repo (required), number (required), fresh, include_files.
github_prsGitHub pull requestsBRead-onlyIdempotent
List pull requests with state, base, head, sort, and direction filters. Returns {items[{number, title, state, draft, author, base, head, updated_at, html_url}], page, per_page, has_more, next_page}.
Inputs: repo (required), base, head, page, +5 more.
github_rate_limitGitHub rate limitARead-onlyIdempotent
Report the authenticated or anonymous GitHub API quota and reset times. Set resource to project a single bucket such as core or search. Call this first when a request is refused with 403 or 429. Returns {auth, resources keyed by bucket with {limit, remaining, reset, used}}; defaults to core and search; pass all: true for every bucket; adds authenticated_as and scopes when the identity opt-in is on.
Inputs: all, resource.
github_readmeGitHub repository readmeARead-onlyIdempotent
Fetch a repository's README through GitHub's readme endpoint, which resolves the default naming variant (README.md, README.zh-CN.md, and friends); use github_file for a specific path. Costs 1 core call. Returns {repo, path, sha, size, encoding, content, binary, truncated}.
Inputs: repo (required), fresh.
github_releaseGitHub releaseARead-onlyIdempotent
Read the latest release or the release for a specific tag, including assets and download URLs. Returns {found, tag_name, name, body, prerelease, draft, published_at, html_url, assets[{name, size, download_count, digest, browser_download_url}]}; found is false when no release exists.
Inputs: repo (required), tag, fresh.
github_releasesGitHub releasesARead-onlyIdempotent
List releases newest first with tag, name, prerelease/draft flags, and dates. Release note bodies are omitted to keep responses small; use github_release for a single release's notes. With include_prereleases=false the page is filtered client-side, so has_more reflects the unfiltered Link header. Returns {items[{tag_name, name, prerelease, draft, published_at, html_url}], page, per_page, has_more, next_page}.
Inputs: repo (required), page, fresh, per_page, +1 more.
github_repoGitHub repositoryARead-onlyIdempotent
Read repository metadata: description, visibility, default branch, stars, forks, open issues, language, license, topics, and timestamps. open_issues includes pull requests. Returns {full_name, description, private, visibility, html_url, default_branch, stars, forks, open_issues, language, license, topics, has_issues, has_discussions, archived, pushed_at, created_at}.
Inputs: repo (required), fresh.
github_repo_activityGitHub repository activityARead-onlyIdempotent
Answer how alive a repository has been over a window, from core endpoints only: pulls opened/merged/closed (closed counts PRs closed without merging) with bot-authored opens and the median hours from opening to merge, issues opened and closed, the window's commit total, active contributors, and the release count. Pulls and issues walk newest-first until the window edge (10-page cap), releases cap at 3 pages; a *_truncated flag reports a walk the cap stopped, and stats GitHub is still computing report null commits/contributors with stats_unavailable. Costs 4-12 core calls, none search. Returns {repo, window_days, generated_at, pulls, median_merge_hours, issues, commits, active_contributors, releases, pulls_truncated, issues_truncated, releases_truncated, stats_unavailable}.
Inputs: repo (required), fresh, window_days.
github_repo_healthGitHub repository healthARead-onlyIdempotent
One-call repository snapshot: stars, true open issue and PR counts, has_issues/has_discussions, window opened/closed counts and per-label open counts (search-backed), and the latest release. Window terms: opened_total = issues created inside the window (any current state); opened_still_open = the subset still open; closed = issues closed inside the window (any creation date). Costs about 10 upstream calls, 9 of them search (within the 30 requests/minute search quota). open_issues here counts issues only; github_repo.open_issues includes pull requests. Returns {repo, window_days, generated_at, stars, forks, license, default_branch, pushed_at, created_at, has_issues, has_discussions, open_issues, open_prs, open_issues_and_prs, window{opened_total, opened_still_open, closed, labels}, search_unavailable, latest_release}.
Inputs: repo (required), fresh, labels, window_days.
github_reposGitHub repository batchARead-onlyIdempotent
Batch repository lookup: fetches up to 20 repositories concurrently, one core call each, and reports per-item success and failure so one missing or inaccessible repo never rejects the call. Returns {results[{repo, ok, data{full_name, description, private, visibility, fork, stars, forks, language, pushed_at, default_branch}} or {repo, ok, error{code, message}}], elapsed_ms}.
Inputs: repos (required), fresh.
github_search_codeGitHub code searchARead-onlyIdempotent
Search code across GitHub. Requires a token; GitHub allows this endpoint only 10 requests/minute and caps results at 1000. Returns {total_count, incomplete_results, items[{repo, path, sha, html_url, text_matches}], page, per_page, has_more, next_page}.
Inputs: query (required), page, fresh, per_page.
github_search_issuesGitHub issue and pull request searchARead-onlyIdempotent
Search issues and pull requests with GitHub search syntax, such as is:issue, is:pr, state:open, or repo:owner/name. For per-repository aggregate counts, use github_repo_health. Returns {total_count, incomplete_results, items[{repo, number, title, state, type, author, updated_at, html_url}], page, per_page, has_more, next_page}.
Inputs: query (required), page, sort, fresh, +2 more.
github_search_reposGitHub repository searchARead-onlyIdempotent
Search repositories by GitHub search syntax. Supports stars, forks, help-wanted-issues, and updated sorting. public_only defaults to true; pass false to include private repositories the token can see. Returns {total_count, incomplete_results, filtered_count, items[{full_name, description, private, visibility, stars, forks, language, topics, license, updated_at, created_at, pushed_at, html_url}], page, per_page, has_more, next_page}.
Inputs: query (required), page, sort, fresh, +3 more.
github_search_usersGitHub user searchARead-onlyIdempotent
Search GitHub users by query syntax — location, language, followers:>=N, repositories:>=N, fullname: qualifiers. Costs 1 search call; the search quota is 30 requests per minute. Returns {total_count, incomplete_results, items[{login, type, html_url}], page, per_page, has_more, next_page}.
Inputs: query (required), page, sort, fresh, +2 more.
github_stargazersGitHub repository stargazersARead-onlyIdempotent
List a repository's stargazers with the time each star was given (star+json media type). Pages are ordered oldest-first by default, so paged calls build a star timeline; compute velocity client-side from starred_at deltas. Costs 1 core call. Returns {items[{login, starred_at}], page, per_page, has_more, next_page}.
Inputs: repo (required), page, fresh, per_page.
github_treeGitHub treeARead-onlyIdempotent
List files and directories in a repository at a ref, using the git trees API. Use recursive=true only when the full tree is needed. summary_only drops entries and returned_entries and answers with total_bytes plus top_dirs totals instead. Returns {ref, path, entries[{path, type, size, sha}], total_entries, returned_entries, summary, truncated, api_truncated}.
Inputs: repo (required), ref, path, fresh, +3 more.
github_trendingGitHub trending approximationARead-onlyIdempotent
Compute a trending approximation from GitHub search, NOT GitHub's trending page: the rising lens lists repositories created inside the window above the star floor and the active lens lists repositories pushed inside the window, both sorted by stars. Star gains are not observable from search alone; every observation is snapshotted under the cache directory, and repeated calls with the same lens, language, and window gain stars_gained against the previous snapshot, so deltas accumulate across calls into real velocity. Costs 2 search calls against the 30 requests/minute search quota. Returns {window, language, lenses{rising, active}, rising_incomplete_results, active_incomplete_results, source}.
Inputs: fresh, limit, window, language, +1 more.
github_userGitHub user profileARead-onlyIdempotent
Read a GitHub user's profile: name, type, bio, company, location, blog, public repository count, and follower counts. Costs 1 core call. Returns {login, name, type, bio, company, location, blog, public_repos, followers, following, created_at, html_url}.
Inputs: user (required).
github_user_eventsGitHub user eventsARead-onlyIdempotent
List a user's public events with the event type, repository, and time; private events are never included, only the public feed. Costs 1 core call. Returns {items[{type, repo, created_at}], page, per_page, has_more, next_page}.
Inputs: user (required), page, fresh, per_page.
github_user_healthGitHub user healthARead-onlyIdempotent
One-call user profile audit: original vs fork split, star totals, top repositories, language distribution, and 90-day push activity — the multi-call walk of a manual audit, compressed to 1. Costs 2-11 core calls, none search. top_repos, languages, and 90-day push activity exclude forks by default (include_forks: true keeps them); originals, forks, fork_share, and total_stars always count them. Returns {user, name, type, public_repos, originals, forks, fork_share, total_stars, top_repos[{full_name, stars, language, pushed_at}], languages, recent_pushes_90d, oldest_push_90d_gap_days, repos_truncated, meta}.
Inputs: user (required), fresh, per_page, include_forks.
github_user_reposGitHub user repositoriesARead-onlyIdempotent
List a user's public repositories with the house projection: visibility, fork status, stars, watchers, language, push time, and description; type defaults to owner. Forks are dropped by default (include_forks: true keeps them) and min_stars keeps repositories at or above the star floor; both filters are client-side, so a filtered page can come back short. sort: stars gathers up to 10 pages of 100 client-side, ranks by stars descending, and reports has_more/next_page from the filtered window with gather_truncated when the cap stopped the gather. Costs 1 core call, up to 10 with sort: stars. Returns {items[{name, full_name, private, visibility, fork, stars, watchers, language, pushed_at, description, html_url}], page, per_page, has_more, next_page, gather_truncated}.
Inputs: user (required), page, sort, type, +5 more.
github_user_starredGitHub user starsARead-onlyIdempotent
List the repositories a user has starred with the time each star was given; the star+json media type supplies starred_at. Costs 1 core call. Returns {items[{repo, stars, language, starred_at, pushed_at}], page, per_page, has_more, next_page}.
Inputs: user (required), page, fresh, per_page.
github_workflow_runGitHub workflow runARead-onlyIdempotent
Read one workflow run. Set include_jobs=true to fetch up to 100 jobs with their step statuses and conclusions. Returns run fields {id, name, workflow_id, run_number, event, status, conclusion, branch, sha, created_at, updated_at, html_url}; adds {jobs[{id, name, status, conclusion, started_at, completed_at, steps[{number, name, status, conclusion}]}], jobs_truncated} when include_jobs is true.
Inputs: repo (required), run_id (required), fresh, include_jobs.
github_workflow_runsGitHub workflow runsARead-onlyIdempotent
List workflow runs for a repository or one workflow, optionally filtered by branch, status, and event. Returns {total_count, items[{id, name, workflow_id, run_number, event, status, conclusion, branch, sha, created_at, updated_at, html_url}], page, per_page, has_more, next_page}.
Inputs: repo (required), page, event, fresh, +4 more.
github_workflowsGitHub workflowsARead-onlyIdempotent
List GitHub Actions workflows in a repository, including disabled and legacy workflows. Returns {total_count, items[{id, name, path, state}], page, per_page, has_more, next_page}.
Inputs: repo (required), page, fresh, per_page.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Most tools are clearly separable by scope: single-item vs list, search vs direct read, and repo/user/workflow/PR resources. A few aggregate and health-oriented tools (github_repo_health, github_repo_activity, github_compare_repos, github_trending) overlap enough to require careful selection, and PRs can be read through both github_pr and github_issue.
All tools use the github_ prefix and snake_case, with a predictable singular/plural convention for single-item vs collection reads and search_* for search tools. A few special names like github_api_get, github_doctor, github_capabilities, and github_user_starred deviate slightly but remain readable and predictable.
41 tools is well above the typical 3-15 range and exceeds the 25+ threshold for a heavy tool set, even for a broad GitHub read-only server. Many tools are specialized, but the large surface increases discovery and selection burden.
The read-only GitHub surface is extensive, covering repos, users, code/files, commits, issues, PRs, releases, workflows, contributors, languages, search, quota, and an api_get escape hatch. Minor gaps remain, such as dedicated PR review/comment coverage, orgs/teams, notifications, and security endpoints, though some are workaroundable.
Maintenance
Related MCP Connectors
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Access the GitHub API, enabling file operations, repository management, search functionality, and…
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables read-only browsing and querying of GitHub repositories, including listing repos, reading files, fetching READMEs, searching code, and viewing commit history via MCP.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to query GitHub repository data through read-only tools, including repo metadata, issues, pull requests, commit statuses, PR diffs, and recent commits. Works with any MCP-compatible client over stdio or Streamable HTTP.1ISC
- AlicenseAqualityBmaintenanceEnables autonomous AI agents and developers to interact with the GitHub REST API for repositories, pull requests, issues, actions, releases, tags, and user/org data through MCP tools. It uses token-efficient response summaries and optional 3-tier read-only safeguards to keep interactions safe and context-window friendly.581 npm1MIT
- AlicenseAqualityCmaintenanceEnables AI agents to ask read-only questions about a repository's history through GitHub APIs, including blame, path history, merge base, PR association, diffs, and file contents, with aggressive caching and no clone required.101MIT