github-mcp

A public read+write MCP server over the GitHub REST API, built to the desktop-mcp/rag-mcp/mcp-factory standard (own pyproject, fastmcp server, honest README, real test suite) with env-gated tool groups (write disabled by default). Not the official GitHub MCP server -- see below.

Quickstart (60 seconds)

pip install jaimenbell-github-mcp

// Add to your MCP host config (e.g. Claude Desktop/Code's mcpServers block)
{
  "mcpServers": {
    "github-mcp": {
      "command": "github-mcp"
    }
  }
}

The write tool group (issue/PR mutations) is off by default -- see Env vars below to enable it.

What this is / is not

This is a reference portfolio implementation demonstrating a hardened read+write MCP server pattern over a real external SaaS API (GitHub) -- env-gated tool groups, typed error/rate-limit handling, auth that degrades gracefully, a real test suite. It exists to show, concretely, "I build read/write MCP servers over external APIs" with a link a client can click.

It is NOT the official GitHub MCP server. It does not aim for parity with GitHub's own MCP offering (GraphQL, Actions, webhooks, GitHub Apps are all out of scope -- see below). It started life as a factory-scaffolded read-only demo (mcp-factory's generated/github_read_server.py) and was hand-hardened into this standalone read+write server -- the scaffold-then-harden path is itself part of the story this repo tells.

Tools (14)

One row per tool -- the two groups below just control default-on/off state, not what exists.

read is always on and works unauthenticated (GitHub's 60 req/hr tier). write is env-gated and OFF by default -- requires GITHUB_MCP_ENABLE_WRITE=1 and GITHUB_TOKEN.

A disabled write call returns a structured policy_refusal error (never a silent no-op, never a crash). A write call with the group enabled but no token returns a structured auth_required error -- the group gate and the token precondition are checked independently, both before any network call.

Write-safety-off-by-default

This is defense-in-depth, mirroring desktop-mcp's input group: harness-level permission prompts are the first gate, but the server itself refuses every write tool unless its own environment explicitly opts in with GITHUB_MCP_ENABLE_WRITE=1, and even then refuses without a GITHUB_TOKEN. A misconfigured or overly-permissive MCP host cannot turn on GitHub mutations this process wasn't deliberately configured to allow. The registration this repo ships with (see ~/.claude.json's github-mcp entry) has the write group absent from env -- enabling it is a deliberate per-registration operator choice, not a code change.

Honest-capabilities table

Every claim below maps to the file that implements it and the test(s) that verify it -- no capability is asserted without a corresponding implementation and test.

Limitations (read before relying on this)

• REST v1 only. No GraphQL API coverage.
• No webhooks / GitHub App auth. Fine-grained PAT only.
• No Actions/workflow-dispatch tools. Issue/PR CRUD is the v1 write surface.
• Unauthenticated read is rate-limited to 60 req/hr by GitHub itself (10 req/min for search) -- expect rate_limited errors under sustained unauthenticated use; set GITHUB_TOKEN (even a read-only fine-grained PAT) to raise this considerably.
• get_file_content truncates past 100KB and reports (rather than decodes) non-UTF-8 files.
• No pagination beyond a single page for list endpoints (limit, capped per-endpoint, is the only page-size control in v1).
• Not registered with the mcp-factory hub. Ships as a standalone repo (own pyproject, system Python312 install), matching the rag-mcp/desktop-mcp model.

Env vars

Usage examples

// A tool call from the MCP host, illustrative -- not a shell command.
{"tool": "get_repo", "arguments": {"owner": "anthropics", "repo": "anthropic-sdk-python"}}
// -> {"ok": true, "full_name": "anthropics/anthropic-sdk-python", "stargazers_count": 1234, ...}

// write group disabled (default):
{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
// -> {"ok": false, "error": {"type": "policy_refusal", "group": "write", "required_env": "GITHUB_MCP_ENABLE_WRITE", ...}}