git-mcp

A remote MCP server that connects Claude to GitHub on behalf of each end user.

1. Auth — runs Claude's custom-connector OAuth flow against a GitHub OAuth App (FastMCP GitHubProvider). Each user logs into GitHub through Claude.
2. Proxy — proxies the official github/github-mcp-server (run in http mode), forwarding each request with the authenticated user's GitHub token. All of GitHub's official MCP tools are exposed to Claude, executed as that user.

Claude custom connector ──HTTPS /mcp──▶ FastMCPProxy (this app)
   auth = GitHubProvider (OAuth App) → per-user GitHub token (get_access_token().token)
   client_factory (per request) → Authorization: Bearer <user token>
                                          ▼
                       github-mcp-server (official, http mode, 127.0.0.1:8082)
                                          ▼
                                   GitHub API (as the user)

Stack

Python 3.12+ · uv · ruff · ty · pytest · fastmcp (pinned).

Setup

make install-dev      # uv sync + pre-commit hooks
cp .env.example .env  # then fill in the values

Create the GitHub OAuth App

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.

• Homepage URL: your BASE_URL (e.g. https://your-app.herokuapp.com)
• Authorization callback URL: <BASE_URL>/auth/callback

Copy the Client ID / secret into .env (GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET).

Develop

make lint        # ruff check + format check + ty
make test        # pytest -n auto
make format      # auto-fix + format + ty

Run locally

The app spawns github-mcp-server http as a subprocess, so you need the binary on PATH (or set GITHUB_MCP_BINARY). Easiest is a local build/binary from the releases; alternatively run the backend yourself in Docker via make run-backend and point BACKEND_MCP_URL at it (then comment out the subprocess spawn for local testing).

make run-dev     # binds 0.0.0.0:$PORT (default 8000), serves /mcp

Test the OAuth + tool flow with the MCP Inspector:

npx @modelcontextprotocol/inspector
# connect to http://localhost:8000/mcp → completes GitHub OAuth → lists tools

Deploy to Heroku (container)

Both processes share localhost, so they run in one dyno via a multi-stage image.

heroku create your-app
heroku stack:set container -a your-app
heroku config:set -a your-app \
  GITHUB_OAUTH_CLIENT_ID=... \
  GITHUB_OAUTH_CLIENT_SECRET=... \
  BASE_URL=https://your-app.herokuapp.com \
  JWT_SIGNING_KEY="$(openssl rand -hex 32)" \
  GITHUB_TOOLSETS=repos,issues,pull_requests,users,context \
  GITHUB_SCOPES="repo read:org read:user"
git push heroku main

Provision Redis so OAuth state survives Heroku's daily dyno cycling — without it every connected client must re-authenticate each day. The add-on sets REDIS_URL automatically:

heroku addons:create heroku-redis:mini -a your-app

BASE_URL and the OAuth App callback (<BASE_URL>/auth/callback) must match the deployed URL exactly.

Add to Claude

Add https://your-app.herokuapp.com/mcp as a custom connector (Streamable HTTP). Claude runs the OAuth flow; after you authorize the GitHub OAuth App, the GitHub tools become available, acting as your GitHub user.

Authentication

OAuth and key-based auth are independent and can run together on one deployment:

• GitHub OAuth (set the OAuth App credentials + a gate via ALLOWED_GITHUB_ORG or ALLOW_UNGATED=1) — for interactive clients like Claude Desktop / claude.ai. Each user acts as themselves via their own GitHub token.
• Key-based (set MCP_API_KEYS + GITHUB_BACKEND_TOKEN) — for a headless app/agent. Clients send Authorization: Bearer <key> and act as the configured backend PAT; a valid key is its own gate (no org check).
• Both — the server serves the OAuth flow and accepts the static keys, so a Claude Desktop connector and a built app can use the same URL at once. Key requests are tagged internally so they forward the backend PAT and skip the org gate, while OAuth requests forward the user's token and are org-gated as usual.

At least one of the two must be configured or the server refuses to start.

Pinning

Keep both moving pieces pinned:

• fastmcp (proxy/auth API moves across versions; targets v3.4.2+).
• ghcr.io/github/github-mcp-server image (pin a digest in the Dockerfile).

Configuration

See .env.example. Notable: GITHUB_TOOLSETS (or all), READ_ONLY=1 to force read-only tools, GITHUB_SCOPES for the OAuth scopes the proxied tools need.