github-read — read-only GitHub MCP server

A production-grade, read-only MCP server for the GitHub REST API. Wire it into Claude Desktop / Claude Code / Cursor and the agent can answer questions about repositories, issues, files, and users — without any write access.

Scaffolded by mcp-factory; the value is the production layer on top: auth-scoping, fail-soft, version-pinning, tests, docs.

Tools

Related MCP server: mcp-github

Install

cd github-read-mcp
python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements.txt   # Windows
# source .venv/bin/activate && pip install -r requirements.txt # macOS/Linux

Dependencies are version-pinned (requirements.txt); a fresh install reproduces the tested build.

Authentication & scoping (read this)

The token is optional:

• No token → the server runs on GitHub's unauthenticated 60 req/hr tier. It works, but rate-limits quickly. It prints a one-line warning to stderr.

• With a token → 5000 req/hr. Use a fine-grained personal access token scoped to read-only:

  • Repository access: only the repos the agent should see (or "public repos").

  • Permissions: Contents: Read-only and Metadata: Read-only. Nothing else.

This server only ever issues HTTP GETs — there is no tool that can write, delete, or mutate anything. Even if handed a broader token, it cannot take a destructive action. Grant the minimum anyway; least privilege is the point.

Set the token via the GITHUB_TOKEN env var (see registration below). Never commit a token.

Register in Claude / Cursor

Add to your MCP config (~/.claude.json under mcpServers, or Cursor's mcp.json):

{
  "mcpServers": {
    "github-read": {
      "command": "C:\\path\\to\\github-read-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "github_mcp.server"],
      "env": { "GITHUB_TOKEN": "github_pat_xxx_your_readonly_token" }
    }
  }
}

The command must be the venv interpreter (so the pinned deps are on the path), and the working directory must be the repo root so -m github_mcp.server resolves. Leave GITHUB_TOKEN as "" to run unauthenticated. Restart the client to pick up the server.

Verify it works

# Hermetic unit/integration suite (no network, no token):
.venv/Scripts/python.exe -m pytest -q

# Live tests against the real unauthenticated GitHub API:
RUN_LIVE_GITHUB_TESTS=1 .venv/Scripts/python.exe -m pytest tests/test_live.py -v

# End-to-end MCP protocol smoke (spawns the server, drives it as a client would):
.venv/Scripts/python.exe scripts/smoke_mcp.py

Fail-soft behavior

Every failure mode returns a structured JSON envelope — a tool call never crashes the agent session:

{ "error": { "type": "rate_limited",
             "message": "GitHub rate limit exhausted on the unauthenticated (60/hr) tier.",
             "hint": "Set a GITHUB_TOKEN to raise the limit to 5000 req/hr.",
             "retry_after_seconds": 118.4 } }

Handled: rate_limited, secondary_rate_limited, unauthorized, forbidden, not_found, invalid_request, is_directory, binary_file, timeout, network_error, bad_response, internal_error. A missing required argument is rejected by the MCP SDK itself (protocol-level isError) before it reaches the server.

Layout

github-read-mcp/
├── mcp.yaml                       # factory manifest (the deliverable spec)
├── github_mcp/
│   ├── server.py                  # MCP server: tools + fail-soft boundary
│   ├── client.py                  # GitHub client: auth, version-pin, fail-soft
│   ├── errors.py                  # error normalization
│   └── _scaffold_generated.py     # original factory stub (provenance / before-after)
├── tests/                         # 31 hermetic + 4 live (network-gated)
├── scripts/smoke_mcp.py           # end-to-end MCP protocol smoke
├── requirements.txt               # pinned runtime deps
└── requirements-dev.txt           # pinned test deps