GitHub MCP Server

What It Does

github-mcp-server is the official Model Context Protocol server from GitHub. It exposes the GitHub platform to any MCP-compatible agent (Claude Code, Cursor, VS Code, Gemini CLI, Windsurf, Zed, OpenCode) so the agent can read repositories and code, manage issues and pull requests, inspect Actions runs, review Dependabot and code-scanning alerts, search discussions, and trigger workflows. It ships in two deployment modes that share one codebase: a remote server hosted at api.githubcopilot.com/mcp/ (OAuth or PAT), and a local server you run yourself via Docker, a pre-built binary, or a Go build. The local binary exposes 84 tools across 20 toolsets by default, expandable to 115 via granular feature flags, plus 2 prompts and 4 MCP resources. It targets developers who want their coding agent to act on GitHub without leaving the chat.

The Good

Test code outweighs production code, which is rare in this category. The repo contains 36,666 lines of non-test Go and 46,486 lines of test Go across 69 test files, plus an e2e suite. For comparison, most MCP servers in the pipeline ship with a handful of tests or none. This is the strongest quality signal a reviewer can cite, and GitHub backs it with a .golangci.yml linter config, a goreleaser pipeline, and a multi-stage Dockerfile whose final image is distroless (gcr.io/distroless/base-debian12).

The full MCP spec is implemented, not just the tools surface. The initialize handshake advertises five capabilities: tools, prompts, resources, completions, and logging. tools/list returned 84 tools with --toolsets=all. prompts/list returned 2 workflow prompts (AssignCodingAgent, issue_to_fix_workflow). resources/list returned 4 UI resources. Most MCP servers in the pipeline implement only the tools capability. This one implements the protocol.

Read-only mode is a real security boundary, verified by testing. Running with --read-only --toolsets=issues,pull_requests,repos reduced the exposed tools to 22, and a name scan found zero write-like tools (no create, update, write, merge, delete, push, fork, star, trigger, dismiss, or manage operations). The filtering happens at tool registration, so the agent never even sees the write tools. Combined with --lockdown-mode, --exclude-tools, --toolsets, and per-toolset OAuth scope filtering, this gives operators granular control over what an agent can do.

Tool dispatch works end to end and returns structured errors. Calling get_me with an invalid token (ghp_invalidtoken_for_testing_12345) returned isError: true with content failed to get user: GET https://api.github.com/user: 401 Bad credentials. That is a clean MCP error response, not a crash or a hang. The server made the API call, received the 401, and surfaced it as structured content the agent can reason about.

Three install paths all work, and the checksum verified on the first try. The pre-built darwin-arm64 tarball (7.2MB compressed, 23MB extracted) matched dcb2c448cec678027e0b727f5b4601f2775c9334e48fb80a3015b2db302de577 in checksums.txt exactly. Version strings are consistent across every surface: the CLI reports 1.5.0, the release tag is v1.5.0, and the MCP initialize response returns serverInfo.version: "1.5.0". No drift. Releases cover 7 platform archives (Darwin, Linux, Windows, each in arm64, x86_64, and i386 where applicable).

The Bad

The README documents a tool-search CLI command that the binary does not ship. The README's "CLI utilities" section instructs users to run github-mcp-server tool-search "issue" --max-results 5. Running that against the v1.5.0 binary returns Error: unknown command "tool-search" for "server". A grep across cmd/, pkg/, and internal/ confirms the string appears only in README.md and nowhere in the Go source. The actual registered subcommands are stdio, http, generate-docs, and list-scopes. This is documentation drift: a feature was either removed or never wired into the release build, but the docs still tell users to run it.

Tool calls without any token hang instead of returning a clean no-credentials error. Calling get_me with no GITHUB_PERSONAL_ACCESS_TOKEN set produced no JSON-RPC response within an 8-second window, because the server has a default OAuth client ID baked in at build time and waits for a browser OAuth callback that can never arrive in a headless context. With an invalid token, the same call returns a clean 401 in under 3 seconds. A headless user who forgets to set the token gets a silent hang rather than a message telling them to set it. The workaround is to always pass a token or use --read-only, but the failure mode is quiet.

generate-docs silently rewrites README.md in the current working directory. Running github-mcp-server generate-docs prints Successfully updated README.md with automated documentation and overwrites whatever README.md exists in your cwd. There is no --dry-run flag, no --output flag, and no confirmation prompt. Running it from the wrong directory clobbers an unrelated file. This is a minor footgun for anyone exploring the CLI subcommands.

Smoke Test Results

Testing was done on the host machine (macOS 26.5, Apple Silicon). The v1.5.0 darwin-arm64 binary was downloaded directly from the GitHub release, checksum-verified, extracted, and exercised through the CLI subcommands and a custom Python MCP stdio client that speaks JSON-RPC over stdin/stdout.

Run A. Install and integrity

$ curl -fsSL -o ghmcp.tar.gz <release>/github-mcp-server_Darwin_arm64.tar.gz
$ curl -fsSL -o ghmcp-checksums.txt <release>/github-mcp-server_1.5.0_checksums.txt
$ shasum -a 256 ghmcp.tar.gz
dcb2c448cec678027e0b727f5b4601f2775c9334e48fb80a3015b2db302de577
$ grep Darwin_arm64 ghmcp-checksums.txt
dcb2c448cec678027e0b727f5b4601f2775c9334e48fb80a3015b2db302de577 ... ✅ matches
$ tar xzf ghmcp.tar.gz
$ ./github-mcp-server --version
GitHub MCP Server
Version: 1.5.0
Commit: 8cd03c018525ae0bafc9b3cdb84ec2133s01bac2
Build Date: 2026-06-27T07:57:10Z ✅

Pass rate: 3 of 3. Checksum matches, binary runs, version prints with matching commit hash.

Run B. Server starts and handshake completes

$ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | ./github-mcp-server stdio
{"jsonrpc":"2.0","id":1,"result":{
 "protocolVersion":"2025-06-18",
 "capabilities":{"completions":{},"logging":{},
 "prompts":{"listChanged":true},"resources":{"listChanged":true},
 "tools":{"listChanged":true}},
 "serverInfo":{"name":"github-mcp-server","version":"1.5.0"},
 "instructions":"The GitHub MCP Server provides tools..."}} ✅

$ ./github-mcp-server list-scopes
OAuth Scopes for Enabled Tools
Enabled Toolsets: actions, code_quality, code_security, context, copilot,
 dependabot, discussions, gists, git, issues, labels, notifications, orgs,
 projects, pull_requests, repos, secret_protection, security_advisories,
 stargazers, users ✅ (20 toolsets)

Pass rate: 2 of 2. The MCP stdio server responds to initialize with the correct protocol version, all five capabilities, and a matching serverInfo version. list-scopes enumerates OAuth scopes per tool across all 20 toolsets.

Full sandbox log →

Run C. Tools respond (functional verification)

$ tools/list (--toolsets=all)
tools returned: 84
distinct name prefixes: 24
sample: actions_get, add_issue_comment, create_branch, get_file_contents,
 list_code_scanning_alerts, merge_pull_request, search_code, update_pull_request ✅

$ tools/call get_me (invalid token ghp_invalidtoken_for_testing_12345)
{"isError":true,"content":[{"type":"text",
 "text":"failed to get user: GET https://api.github.com/user: 401 Bad credentials []"}]} ✅

$ tools/list (--read-only --toolsets=issues,pull_requests,repos)
read-only tools total: 22
write-like names remaining: NONE (read-only enforced) ✅

$ prompts/list
prompts: 2 (AssignCodingAgent, issue_to_fix_workflow) ✅
$ resources/list
resources: 4 (get_me_ui, issue_write_ui, pr_edit_ui, pr_write_ui) ✅

Functional pass rate: 5 of 5. Tool enumeration, tool dispatch with auth error handling, read-only enforcement, prompts, and resources all returned correct structured responses.

What the runs tell you

The install path is one-shot and verified: download, checksum, run. The server starts and advertises the full MCP capability set over stdio without configuration. The core value claim (agents can act on GitHub through a standard protocol) holds up under direct testing, since tool dispatch returned real API errors from GitHub on an invalid token and read-only mode filtered the tool surface exactly as documented. The only thing that did not work as documented was the tool-search CLI command, which is a documentation gap rather than a functional failure of the server itself.

Setup Walkthrough

1. Pick a deployment mode. For the easiest path, use the remote server: add {"type":"http","url":"https://api.githubcopilot.com/mcp/"} to your MCP host config (VS Code 1.101+, Claude Desktop, Cursor, Windsurf). Authenticate via OAuth on first use or pass a PAT in the Authorization header.
2. For a local server, the Docker path is the documented default: docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server. The image is at ghcr.io/github/github-mcp-server and runs stdio by default.
3. For a local server without Docker, download the pre-built archive for your platform from the latest release. Verify the SHA-256 against github-mcp-server__checksums.txt (it matched on the first try in testing). Extract and run ./github-mcp-server stdio with GITHUB_PERSONAL_ACCESS_TOKEN set in the environment.
4. Restrict the tool surface with --toolsets. The default enables context, repos, issues, pull_requests, users, and copilot. Use --toolsets=all for all 20 toolsets (84 tools), or scope tightly with --toolsets=issues,repos to reduce context size.
5. For read-only access, add --read-only. Testing confirmed this drops all write, create, merge, delete, and push tools from the surface.
6. For enterprise or GitHub Enterprise Server deployments, set --gh-host to your instance hostname and consult docs/policies-and-governance.md for PAT, OAuth App, GitHub App, and SSO considerations.

Note: building from source requires Go 1.25, which is very recent. Use the pre-built binary or Docker image if your Go toolchain is older.

Alternatives

1. wonderwhy-er/DesktopCommanderMCP (6.2K stars) - a general terminal and filesystem control MCP server, not GitHub-specific. It can run git and gh commands locally but does not expose structured GitHub API tools. Prefer github-mcp-server when you want typed tool calls against the GitHub API rather than shell command execution.
2. googleapis/mcp-toolbox (15.7K stars) - Google's official MCP server for databases (Cloud SQL, Spanner, AlloyDB). A different vertical (databases, not source control) from a different vendor, but the same official-vendor-MCP-server archetype. Useful as a complement, not a replacement.
3. CLI gh wrapped in a generic shell MCP - the lowest-friction alternative is to skip a dedicated MCP server and let your agent call the gh CLI through a terminal tool. This loses structured tool schemas, read-only enforcement, and toolset filtering, but avoids installing another binary.