GitHub MCP Server

A small, working Model Context Protocol server that exposes read-only GitHub tools to an LLM client such as Claude Desktop. Built with the official mcp Python SDK (stdio transport) and direct GitHub REST calls via requests.

The design goal is a handful of tools that work end-to-end rather than a large stubbed-out surface: an LLM can browse a repo's open issues and PRs, drill into a specific issue's discussion, and summarize recent activity.

Tools

All tools take repo in owner/name form (e.g. python/cpython). GitHub API errors (bad repo names, 404s, rate limits, bad tokens) are caught and returned as a readable error message the model can act on, never a stack trace.

Related MCP server: GitHub Tools MCP Server

Handling failure

Every request goes through one helper, _gh_get, which retries the failures a second attempt can actually fix and fails fast on the ones it can't:

Backoff is exponential with jitter (~1s, ~2s, ~4s), capped at 20s, and a server-supplied Retry-After overrides the computed delay. When GitHub sends one, we listen to it rather than guessing. The jitter matters when several tool calls fail at once: without it they retry in lockstep and hit the API in a thundering herd.

Whatever the outcome, the caller sees a readable error string it can act on — never a stack trace, and never a silent hang.

Setup

Requires Python 3.10+.

pip install -r requirements.txt

Optionally set a GitHub token — not required for public repos, but it raises the API rate limit from 60 to 5,000 requests/hour and enables private repos your token can see:

# PowerShell (current session)
$env:GITHUB_TOKEN = "ghp_your_token_here"

The token is only ever read from the environment — never hardcoded or written to disk.

Verify it works (before touching Claude Desktop)

Two suites, for two different questions.

Unit tests — the GitHub API is mocked, so they need no network and no token. This is what CI runs on every push:

pip install pytest
pytest test_server.py

Live smoke test — calls each tool function directly against a real public repo and also exercises the error paths, so you can confirm the GitHub integration works before wiring the server into Claude Desktop:

python test_live.py                        # defaults to modelcontextprotocol/python-sdk
python test_live.py owner/some-other-repo  # or pick your own

You should see 6/6 checks passed.

Register in Claude Desktop

1. Open the config file (create it if missing):

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the server under mcpServers, using absolute paths for both the Python interpreter and server.py:

{
  "mcpServers": {
    "github": {
      "command": "C:\\Users\\jeswi\\AppData\\Local\\Python\\pythoncore-3.14-64\\python.exe",
      "args": ["C:\\Users\\jeswi\\OneDrive\\Documents\\Resume Project\\Github-MCP\\server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

The env block is how Claude Desktop passes the token to the server process; omit it entirely for anonymous access to public repos.

Use the real interpreter path, not the Windows Store alias. (Get-Command python).Source often returns ...\WindowsApps\python.exe, which is a shim that fails when launched as a subprocess. Get the true path with:

python -c "import sys; print(sys.executable)"

3. Fully quit and restart Claude Desktop (system tray → Quit, not just closing the window).

4. Confirm the connection: in a new chat, the tools icon (below the message box) should list the four github tools.

Example prompts

Prompts that naturally trigger each tool:

• "What are the open issues in modelcontextprotocol/python-sdk right now?" → list_open_issues

• "Are there any open pull requests in pallets/flask? Which ones are drafts?" → list_open_prs

• "Summarize the discussion on issue #3307 in modelcontextprotocol/python-sdk." → get_issue

• "How active has python/cpython been in the last two weeks? What got merged or closed?" → search_repo_activity

• "Look at recent activity in anthropics/anthropic-sdk-python and tell me if any of the newly opened issues look like duplicates of each other." → search_repo_activity + get_issue

How it works

Claude Desktop ── stdio (JSON-RPC / MCP) ──> server.py ── HTTPS ──> api.github.com

• server.py registers four plain Python functions as MCP tools; their docstrings become the tool descriptions the LLM reads when deciding what to call.

• The server runs over stdio: Claude Desktop launches it as a subprocess and speaks MCP over stdin/stdout. No ports, no web server, no persistence.

• Tool results are returned as structured JSON, so the model gets fields (number, author, labels, URL) rather than prose to parse.

Scope

Deliberately excluded: write operations (creating issues, commenting), OAuth flows, a web UI, and any database. This is a clean local demo of the MCP tool-serving pattern.