Purpose
github-mcp is a public read-write reference MCP server built on the GitHub REST API, used to demonstrate patterns for implementing a hardened read-write MCP server on a real external SaaS API, including environment-variable-gated tool groups, typed error and rate limit handling, authentication mechanisms that degrade gracefully, and a real test suite. The project explicitly states that it is not the official GitHub MCP server and does not aim for parity with the official MCP product.
Main capabilities
- Provides two tool groups, read and write; the tool groups only control the default enabled or disabled state, not whether the tools exist.
- The read tool group is always enabled and can be used without authentication, running under GitHub's unauthenticated limit of 60 requests/hour.
- The write tool group (issue/PR changes) is disabled by default and requires setting GITHUB_MCP_ENABLE_WRITE=1 and providing GITHUB_TOKEN to enable it; the group gating and the token precondition are checked independently, and both are completed before any network call.
- Rate limits and errors are handled in a typed manner; calling a disabled write tool returns a structured policy_refusal error, and enabling the write group without a token returns a structured auth_required error, without silently doing nothing or crashing.
- Provides an honest capabilities table, where each capability claim corresponds to an implementation file and a verification test.
Usage
- In a Python 3.12+ environment, run pip install -r requirements.txt.
- (Optional) Generate a fine-grained PAT with scopes covering the repositories that need read-write permissions (Issues read-write, Pull requests read-write, and Contents read are sufficient for v1). Read tools require no token.
- Add it to the MCP host configuration (for example ~/.claude.json).
- If write tools need to be enabled for a given deployment, add "GITHUB_MCP_ENABLE_WRITE": "1" to that entry's env block; this is an operational decision at registration time, not a code change.
The project is registered as github-mcp in ~/.claude.json via stdio, using the system Python312; the read group is always enabled, and the write group is disabled by default when absent from env.
Applicable scenarios
Suitable for reference portfolio scenarios that want to show "I can build read-write MCP servers for external APIs" with concrete clickable links, and also suitable for developers who need to demonstrate hardened read-write MCP server patterns on the real GitHub API.
Limitations
- Covers only REST v1, and does not support the GraphQL API.
- Does not support webhooks or GitHub App authentication, only fine-grained PATs.
- Does not provide Actions/workflow-dispatch tools; issue/PR CRUD is the write operation scope of v1.
- Unauthenticated reads are limited by GitHub itself to 60 requests/hour (10 requests/minute for search), and sustained unauthenticated use will produce rate_limited errors; setting GITHUB_TOKEN (even a read-only fine-grained PAT) can significantly increase the quota.
- get_file_content truncates content over 100KB, and reports rather than decodes non-UTF-8 files.
- List endpoints do not support pagination beyond a single page; limit (capped per endpoint) is the only page size control in v1.
- Not registered with the mcp-factory hub, and distributed as a standalone repository (with its own pyproject, installed with system Python312).
- Commercial support is maintained by Jaimen Bell.
Missing information: no specific pricing, list of supported platforms, or performance results data is provided.
