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.

Tool groups

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.

... View full README on GitHub