jaimenbell/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)
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.
| Tool | Group | What it does |
|---|---|---|
| get_repo | read | Repo metadata (stars, language, license, default branch, archived flag...) |
| list_issues | read | List issues on a repo (PRs filtered out) |
| get_issue | read | Fetch a single issue |
| list_pull_requests | read | List pull requests on a repo |
| get_pull_request | read | Fetch a single pull request |
| get_file_content | read | Read a repo file's content (base64-decoded, binary detected not decoded) |
| search_repos | read | Search public repositories |
| get_user | read | Public user/org profile |
| list_commits | read | List commits on a branch/ref |
| create_issue | write | Open an issue |
| comment_on_issue | write | Comment on an issue/PR |
| update_issue_state | write | Open/close an issue |
| add_labels | write | Add labels to an issue/PR |
| create_pr_review_comment | write | Create a PR review comment on a diff line |
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.
| Claim | Implementation | Verified by |
|---|---|---|
| Repo metadata (stars, language, license, default branch, archived flag...) | github_mcp/groups/read.py::get_repo | tests/test_read.py::TestGetRepo, live: tests/test_live_smoke.py::test_live_get_repo_real_json |