mcp-github-server

An MCP server exposing GitHub repository data — commits, issues, contributor activity — as typed, callable tools that any MCP-compatible LLM client (Claude Desktop, Claude Code, others) can discover and use.

Demo

Claude Desktop asking about a real repo — it discovers recent_commits, requests approval to call it with the right arguments, then does the same for codebase_insights on a follow-up question. No custom integration code, no prior knowledge of this API — just the tool descriptions this server advertises.

Related MCP server: github-mcp

Architecture

flowchart LR
    A[Claude Desktop<br/>or any MCP client] -- "MCP over stdio" --> B[mcp-github-server]
    B -- "GitHub REST API" --> C[(GitHub)]
    C -- JSON --> B
    B -- "typed, validated tool results" --> A

The client launches server.py as a local subprocess and talks to it over stdio using the MCP protocol — no network server to run or expose.

Tools

Six of seven tools work against any public GitHub repo with zero setup — no token, no auth, no config beyond pointing a client at this server. Responses are Pydantic-validated (RepoSummary, Commit, Issue, Contributor, CodebaseInsights, WeeklyCommitCount, CodeSearchResult) and cached in-memory for 5 minutes, so repeated identical calls don't re-hit the GitHub API.

search_codebase is the one exception: GitHub's code search sits in its own, much stricter rate-limit bucket (code_search, separate from core) that isn't reliable unauthenticated, so this tool requires GITHUB_TOKEN and returns a clear error without it, rather than silently failing under load. It also only indexes a repo's default branch and excludes some large files and forks — a query can legitimately come back empty for code that exists elsewhere in the repo.

commit_frequency note: it calls GitHub's stats endpoint, which computes results asynchronously for repos it hasn't cached recently. On a cold cache it returns a "still computing, try again in a few seconds" message instead of an empty or wrong result — this is a real GitHub API quirk, not a bug here.

Setup

python -m venv .venv
.venv/Scripts/activate   # .venv/bin/activate on macOS/Linux
pip install -e ".[dev]"

Optional: higher rate limit

Unauthenticated requests are capped at 60/hour by GitHub, which is fine for a demo. Set GITHUB_TOKEN (copy .env.example to .env) for 5,000/hour — never required.

Running

python src/server.py

The server communicates over stdio — it's meant to be launched as a subprocess by an MCP client, not run standalone for interactive use.

Connect to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "github-intelligence": {
      "command": "/absolute/path/to/.venv/Scripts/python.exe",
      "args": ["/absolute/path/to/src/server.py"]
    }
  }
}

Restart Claude Desktop, then ask something like "what are the 5 most recent commits on <owner>/<repo>?"

Tests

pytest tests/

GitHub's API is fully mocked — no live network or token needed to run the suite.

Why MCP instead of a REST API

A REST API requires the caller to already know its exact endpoints and response shapes ahead of time — someone has to read docs and write integration code for that specific API before anything can use it. An MCP server instead advertises its own tools, descriptions, and expected inputs at runtime, so any compatible client can discover and call them without custom integration code being written per API. This project is a callable capability an LLM can reason about choosing to use, not a fixed endpoint a human developer wires up by hand once.