github-insights-mcp

An MCP server that gives Claude (or any MCP host) read-only tools for exploring public GitHub repositories: search, repository details, READMEs, contributors, commit activity, and side-by-side comparison.

Built on the MCP Python SDK v2 (MCPServer) with async httpx2.

Tools

Related MCP server: GitBridge

Design choices

• Errors the model can act on. GitHub failures (404s, rate limits, rejected tokens, timeouts) are raised as MCP ToolErrors with specific messages, such as "Repository nobody/nothing was not found (it may be private or misspelled)." The model reads the message and can correct itself. Unexpected exceptions are reported generically, so internals never leak into the conversation.

• Validated inputs. Every parameter carries a description and bounds in the tool schema, so out-of-range values are rejected before any request is made. Owner and repository names are checked against GitHub's character set, which also blocks path tricks such as owner="..".

• GitHub quirks handled. Statistics endpoints answer 202 Accepted while GitHub computes them, so get_commit_activity retries briefly instead of failing. Renamed repositories are followed through redirects. GitHub's open_issues_count includes pull requests, so it is reported as open_issues_and_prs.

• A testable core. All GitHub logic lives in github_client.py, which has no MCP imports; server.py only declares the tools. The test suite runs offline against a mock transport, plus in-memory protocol tests through the SDK's Client.

Setup

Requires Python 3.10 or newer.

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

A GitHub token is optional but recommended. Without one, GitHub allows 60 requests per hour (10 searches per minute); with one, 5,000 requests per hour (30 searches per minute). A fine-grained personal access token with read-only access to public repositories is enough.

export GITHUB_TOKEN=github_pat_...

Try it in the MCP Inspector

npx -y @modelcontextprotocol/inspector .venv/bin/python server.py

On Windows, use .venv\Scripts\python.exe instead of .venv/bin/python. Running python server.py by itself just waits silently: it is a stdio server that expects an MCP host on the other end.

Use it from Claude Desktop

Add this to claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\), then restart Claude Desktop:

{
  "mcpServers": {
    "github-insights": {
      "command": "/absolute/path/to/github-insights-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/github-insights-mcp/server.py"],
      "env": { "GITHUB_TOKEN": "github_pat_..." }
    }
  }
}

Point command at the virtual environment's Python rather than a bare python. The host launches the server outside your shell, where python may be an interpreter without these dependencies. On Windows the path looks like C:\\Users\\you\\github-insights-mcp\\.venv\\Scripts\\python.exe (backslashes doubled, since this is JSON).

Then try a prompt like: "Compare pallets/flask and fastapi/fastapi, then summarize the README of whichever had more commits in the last month."

Use it from Claude Code

claude mcp add-json github-insights '{"type":"stdio","command":"/absolute/path/to/github-insights-mcp/.venv/bin/python","args":["/absolute/path/to/github-insights-mcp/server.py"],"env":{"GITHUB_TOKEN":"github_pat_..."}}'
claude mcp list

add-json sidesteps a known argument-ordering pitfall in claude mcp add --env.

Tests

python -m unittest discover -s tests -v

No network or token needed: tests/fake_github.py serves canned GitHub responses through httpx2.MockTransport. pytest runs the same suite if you have it installed.

Project layout

github_client.py   GitHub REST calls, input validation, error messages (no MCP imports)
server.py          MCP tool declarations: schemas, annotations, error translation
tests/             offline unit tests and in-memory MCP protocol tests

Ideas for next steps

• Cache responses for a few minutes to stretch the rate limit during long sessions

• Add a list_issues tool (open issues filtered by label) for triage workflows

• Serve over Streamable HTTP (mcp.run(transport="streamable-http")) for remote use

License

MIT