github-mcp

GitHub MCP server for Claude Code, Cursor, Cline, Windsurf, and any MCP-compatible client.

Exposes GitHub tools (issues, pull requests, code search, file content) to your LLM via the Model Context Protocol.

Features

• 🔁 Connection pooling & retry — single HTTP client per process, exponential backoff on 429/5xx, honors Retry-After.

• 🛡️ Typed errors — GitHubError carries HTTP status, parsed message, and endpoint.

• ✅ Input validation — catches bad inputs before the network round-trip.

• 📄 Text files decoded — get_file_content returns UTF-8 text under decoded_content for text files.

• 🧪 Fully tested — 75 mock-based tests, plus opt-in live integration tests.

• 🪶 Tiny — three runtime deps (mcp, httpx, pydantic); no PyGithub.

Tools exposed

Full parameter docs: docs/USAGE.md.

Install

pip install github-mcp

Or with uv:

uv tool install github-mcp

Requires Python 3.10+.

Authenticate

1. Create a GitHub personal access token:

   • Fine-grained (recommended): https://github.com/settings/personal-access-tokens/new

   • Classic (legacy): https://github.com/settings/tokens/new

2. Set the token:

   export GITHUB_TOKEN="ghp_..."   # macOS / Linux / Git Bash
   # or PowerShell: $env:GITHUB_TOKEN = "ghp_..."

   See docs/AUTH.md for Windows and per-client config.

Configure your client

Claude Code

claude mcp add --transport stdio github -- github-mcp

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "github-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Cline / Windsurf

See your client's docs for adding a stdio MCP server. Command: github-mcp. Env: GITHUB_TOKEN.

Example prompts

"List the 5 most recent open issues in cli/cli labeled bug."

"Get issue #1234 in cli/cli and summarize the discussion."

"Create a new issue in my-org/my-repo titled Bug: login fails on Safari with body Steps to reproduce: ...."

"Show me the contents of src/main.py in cli/cli on the main branch."

"Search GitHub for function authenticate in cli/cli."

Development

git clone https://github.com/AbdeeBuilds/github-mcp
cd github-mcp
python -m venv .venv
source .venv/Scripts/activate   # Git Bash on Windows
pip install -e ".[dev]"
pytest                          # mock-based suite
GITHUB_TOKEN=*** pytest tests/test_live.py -v   # live integration

Quality gates (run on every PR):

ruff check src tests
ruff format --check src tests
mypy src

License

MIT — see LICENSE.