GitHub Tools MCP Server

A real Model Context Protocol server exposing read-only tools against the GitHub REST API — installable into Claude Desktop or Claude Code in under a minute — plus a separate web demo exercising the same tool logic through an ordinary chat UI.

Live demo: https://mcp-demo-phi.vercel.app/demo

Status: what this is and isn't

Working and deployed. All 5 tools verified against real GitHub data, 42 automated checks across 3 test suites, and the full app confirmed live on the real production URL. See DESIGN_LOG.md for the running, honest account of every decision and bug along the way.

The web demo is NOT an MCP transport. It's plain FastAPI calling the same tools.py functions directly as Python, not speaking the MCP protocol. Genuinely useful distinction to be precise about — see DESIGN_LOG.md section 3 for why a real remote MCP transport isn't attempted here.

Architecture

                    ┌─────────────────────┐
                    │      tools.py        │  <- 5 pure functions, no
                    │  (GitHub REST calls   │     MCP-specific code
                    │   via github_client)   │
                    └──────────┬───────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                  │
    ┌─────────▼─────────┐            ┌───────────▼──────────┐
    │     server.py       │            │     api/index.py       │
    │  MCPServer, stdio    │            │  FastAPI, POST /chat    │
    │  transport            │            │  real Claude tool-      │
    │  -> Claude Desktop/    │            │  calling loop over       │
    │     Claude Code        │            │  the same tools           │
    └─────────────────────┘            └────────────────────────┘
     THE MCP SERVER                      A PLAIN HTTP DEMO OF
     (the real deliverable)              THE SAME TOOL LOGIC

Setup

cp .env.example .env   # GITHUB_TOKEN (both halves), ANTHROPIC_API_KEY (web demo only)
pip install -r requirements.txt

Run the MCP server locally

python3 server.py

Add to Claude Desktop: edit %APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), merging in the contents of claude_desktop_config.example.json (fill in your real GITHUB_TOKEN and the absolute path to server.py), then restart Claude Desktop. Add to Claude Code: claude mcp add or edit your project's .mcp.json the same way.

Manual interactive dev workflow: the SDK ships an inspector for poking at the server by hand without a full client — npx @modelcontextprotocol/inspector python3 server.py.

Run the web demo locally

export $(cat .env | xargs)
uvicorn api.index:app --reload --port 8020

Design log

Every non-obvious decision, plus the SDK API surface verified against the actually-installed package rather than assumed from possibly-stale docs, is in DESIGN_LOG.md.