# github-fetcher MCP server

> Provides a read-only GitHub interface for AI agents with proxy support, ETag caching, and automatic credential reuse for reliable repository access.

- Repository: https://github.com/KurvCygnus/github-fetcher
- Page: https://hostedmcp.org/servers/kurvcygnus/github-fetcher
- Transport: stdio
- Stars: 0
- License: MIT

## Install

### Claude Code

```sh
claude mcp add github-fetcher -- npx -y @kurvcygnus/github-fetcher
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": [
        "-y",
        "@kurvcygnus/github-fetcher"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "github-fetcher": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@kurvcygnus/github-fetcher"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"github-fetcher","type":"stdio","command":"npx","args":["-y","@kurvcygnus/github-fetcher"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": [
        "-y",
        "@kurvcygnus/github-fetcher"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add github-fetcher -- npx -y @kurvcygnus/github-fetcher
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.github-fetcher]
command = "npx"
args = ["-y", "@kurvcygnus/github-fetcher"]
```

### Gemini CLI

```sh
gemini mcp add -s user github-fetcher npx -- -y @kurvcygnus/github-fetcher
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": [
        "-y",
        "@kurvcygnus/github-fetcher"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GITHUB_TOKEN` | no | no |  |

## Tools (34)

- `github_rate_limit`: 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. (read-only)
- `github_repo`: 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}. (read-only)
- `github_tree`: 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}. (read-only)
- `github_file`: 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}. (read-only)
- `github_readme`: 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}. (read-only)
- `github_commits`: 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}. (read-only)
- `github_branches`: List branches with their head sha and protection state. Returns {items[{name, sha, protected}], page, per_page, has_more, next_page}. (read-only)
- `github_issue`: 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. (read-only)
- `github_issues`: 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}. (read-only)
- `github_pr`: 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. (read-only)
- `github_prs`: 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}. (read-only)
- `github_release`: 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. (read-only)
- `github_releases`: 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}. (read-only)
- `github_search_repos`: 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}. (read-only)
- `github_search_code`: 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}. (read-only)
- `github_search_issues`: 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}. (read-only)
- `github_search_users`: 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}. (read-only)
- `github_workflows`: 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}. (read-only)
- `github_workflow_runs`: 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}. (read-only)
- `github_workflow_run`: 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. (read-only)
- `github_api_get`: 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?}. (read-only)
- `github_repo_health`: 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}. (read-only)
- `github_capabilities`: 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}]}]}. (read-only)
- `github_compare_repos`: 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}. (read-only)
- `github_user`: 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}. (read-only)
- `github_user_repos`: 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}. (read-only)
- `github_user_starred`: 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}. (read-only)
- `github_user_events`: 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}. (read-only)
- `github_languages`: 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}. (read-only)
- `github_contributors`: 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}. (read-only)
- `github_repo_activity`: 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}. (read-only)
- `github_repos`: 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}. (read-only)
- `github_compare_refs`: 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?}. (read-only)
- `github_doctor`: 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}}. (read-only)

## FAQ

### 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.
