github-mcp

github-mcp

一个通过 GitHub REST API 提供公开读写能力的 MCP 服务，遵循 desktop-mcp/rag-mcp/mcp-factory 标准（独立的 pyproject、fastmcp 服务、真实可靠的 README、完整的测试套件），并通过环境变量控制 工具组（默认禁用写入）。这不是 GitHub 官方 MCP 服务 ——详情见下文。

快速开始（60 秒）

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"
    }
  }
}

write 工具组（问题/PR 修改）默认关闭——如需启用，请参阅下文的 环境变量。

是什么 / 不是什么

这是一个参考作品集实现，用于展示基于真实外部 SaaS API（GitHub）的强化型 读写 MCP 服务模式——通过环境变量控制工具组、强类型错误/速率限制处理、可平稳降级的身份验证以及完整的测试套件。它的存在是为了通过一个客户端可以点击的链接，具体展示“我能构建基于外部 API 的读写 MCP 服务”。

**这不是 GitHub 官方 MCP 服务。**它不打算与 GitHub 自己的 MCP 服务保持功能一致（GraphQL、Actions、webhook、GitHub Apps 均不在范围内——详见下文）。它最初是一个由工厂脚手架生成的只读演示（mcp-factory 的 generated/github_read_server.py），之后经过手动强化，成为这个独立的读写服务——先搭建脚手架再强化的过程本身，也是本仓库要讲述的一部分。

工具（14 个）

每个工具占一行——下面的两个组只控制默认启用或禁用状态， 不决定工具是否存在。

工具	组	功能
get_repo	read	仓库元数据（星标数、语言、许可证、默认分支、归档标志……）
list_issues	read	列出仓库中的问题（已过滤掉 PR）
get_issue	read	获取单个问题
list_pull_requests	read	列出仓库中的拉取请求
get_pull_request	read	获取单个拉取请求
get_file_content	read	读取仓库文件的内容（base64 解码；检测二进制文件但不解码）
search_repos	read	搜索公开仓库
get_user	read	公开用户/组织资料
list_commits	read	列出分支/ref 上的提交
create_issue	write	创建问题
comment_on_issue	write	在问题/PR 上发表评论
update_issue_state	write	打开/关闭问题
add_labels	write	为问题/PR 添加标签
create_pr_review_comment	write	在差异行上创建 PR 审查评论

read 始终启用，无需身份验证即可使用（GitHub 每小时 60 次请求的等级）。 write 由环境变量控制，且默认关闭——需要同时设置 GITHUB_MCP_ENABLE_WRITE=1 和 GITHUB_TOKEN。

禁用状态下调用写入工具会返回结构化的 policy_refusal 错误（不会静默无操作，也不会崩溃）。启用工具组但未提供令牌时调用写入工具，则会返回结构化的 auth_required 错误——工具组开关和令牌前置条件会分别检查，且均在发起任何网络调用之前进行。

默认关闭写入安全功能

这是纵深防御设计，与 desktop-mcp 的 input 组一致：宿主级权限提示是第一道关卡，但除非通过 GITHUB_MCP_ENABLE_WRITE=1 在环境中明确启用，否则服务本身会拒绝所有写入工具；即使启用了，缺少 GITHUB_TOKEN 时也会拒绝。配置错误或权限过宽的 MCP 主机无法启用此进程未被有意配置为允许的 GitHub 修改操作。此仓库提供的注册配置（参见 ~/.claude.json 中的 github-mcp 条目）未在 env 中包含写入组——启用该组是操作人员针对特定注册配置有意作出的选择，而非代码更改。

能力声明核对表

以下每项声明均对应实现它的文件及验证它的测试——每项能力声明都有相应的实现和测试作为依据。

声明	实现	验证方式
仓库元数据（星标数、语言、许可证、默认分支、归档标记……）	github_mcp/groups/read.py::get_repo	tests/test_read.py::TestGetRepo，实时测试：tests/test_live_smoke.py::test_live_get_repo_real_json
列出 / 获取议题（从列表中筛除 PR）	github_mcp/groups/read.py::list_issues、get_issue	tests/test_read.py::TestListIssues、TestGetIssue
列出 / 获取拉取请求	github_mcp/groups/read.py::list_pull_requests、get_pull_request	tests/test_read.py::TestListPullRequests、TestGetPullRequest
读取仓库文件内容（进行 base64 解码，检测到二进制文件时不解码）	github_mcp/groups/read.py::get_file_content	tests/test_read.py::TestGetFileContent
搜索公开仓库	github_mcp/groups/read.py::search_repos	tests/test_read.py::TestSearchRepos
公开用户 / 组织资料	github_mcp/groups/read.py::get_user	tests/test_read.py::TestGetUser
列出分支 / 引用上的提交	github_mcp/groups/read.py::list_commits	tests/test_read.py::TestListCommits
创建议题	github_mcp/groups/write.py::create_issue	tests/test_write.py::TestCreateIssue
在议题 / PR 上发表评论	github_mcp/groups/write.py::comment_on_issue	tests/test_write.py::TestCommentOnIssue
打开 / 关闭议题	github_mcp/groups/write.py::update_issue_state	tests/test_write.py::TestUpdateIssueState
为议题 / PR 添加标签	github_mcp/groups/write.py::add_labels	tests/test_write.py::TestAddLabels
针对差异中的某一行创建 PR 审查评论	github_mcp/groups/write.py::create_pr_review_comment	tests/test_write.py::TestCreatePrReviewComment
写入工具组默认关闭；禁用时会结构化地拒绝请求	github_mcp/config.py::group_enabled、gated_write	tests/test_config.py::TestGroupEnabled、tests/test_write.py::TestGateDisabledByDefault
即使启用了工具组，写入工具也需要令牌	github_mcp/config.py::check_write_preconditions	tests/test_config.py::TestCheckWritePreconditions、tests/test_write.py::TestAuthRequiredWhenGroupEnabled
使用细粒度 PAT 身份验证；缺少令牌时降级为未身份验证级别	github_mcp/client.py::_headers	tests/test_client.py::TestAuthHeaderInjection、tests/test_read.py::TestUnauthDegrade
GitHub 主要速率限制（403 + X-RateLimit-Reset）和次要速率限制（403 + Retry-After，无 X-RateLimit-Remaining）都会作为带有重置 / 重试时间的类型化错误返回，绝不会导致崩溃	github_mcp/client.py::_rate_limit_error、_is_rate_limit_response	tests/test_client.py::TestRateLimitError、tests/test_client.py::TestRateLimitError::test_secondary_rate_limit_no_ratelimit_headers_retry_after_only、tests/test_read.py::TestUnauthDegrade::test_get_repo_rate_limited_without_token_is_typed
格式错误的所有者 / 仓库 / 路径（控制字符等）若会触发 httpx.InvalidURL，则会作为类型化错误返回，绝不会抛出未捕获的异常	github_mcp/client.py::request	tests/test_client.py::TestNetworkError::test_malformed_path_raises_invalid_url_caught_as_network_error
通用 4xx / 5xx 错误会作为类型化错误返回，绝不会导致崩溃	github_mcp/client.py::_api_error	tests/test_client.py::TestApiError
非 JSON / 格式错误的响应和网络故障会作为类型化错误返回	github_mcp/client.py::_handle_response、request	tests/test_client.py::TestDecodeError、TestNetworkError

局限性（依赖前请阅读）

• 仅支持 REST v1。 不覆盖 GraphQL API。
• 不支持 Webhook / GitHub App 身份验证。 仅支持细粒度 PAT。
• 没有 Actions/工作流派发工具。 Issue/PR 的 CRUD 是 v1 的写入范围。
• 未通过身份验证的读取请求受 GitHub 自身的速率限制，每小时 60 次（搜索每分钟 10 次）——持续未通过身份验证地使用时，预计会出现 rate_limited 错误；设置 GITHUB_TOKEN（即使是只读的细粒度 PAT）也能大幅提高限额。
• get_file_content 会截断超过 100KB 的内容，并会报告而非解码非 UTF-8 文件。
• 列表端点不支持跨页分页（limit 受各端点限制，是 v1 中唯一的页面大小控制项）。
• 未在 mcp-factory hub 中注册。 作为独立仓库发布（使用自己的 pyproject，通过系统 Python312 安装），与 rag-mcp/desktop-mcp 模式一致。

环境变量

变量	作用	默认值
GITHUB_MCP_ENABLE_WRITE	启用 write 工具组	未设置（关闭）
GITHUB_TOKEN	细粒度 PAT；不设置也可读取（但未经身份验证的速率限额较低），写入则需要此令牌	未设置
GITHUB_MCP_LIVE	设置为 1 以运行真实网络冒烟测试（见“测试”）	未设置（跳过）

使用示例

// 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", ...}}

// write group enabled, no token set:
{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
// -> {"ok": false, "error": {"type": "auth_required", "tool": "create_issue", ...}}

测试

CI（.github/workflows/ci.yml）会在每次推送/PR 时运行此测试套件；如果上方的 Tests 徽章与测试套件实际报告的结果不符，就会导致构建失败——参见 scripts/check_readme_counts.py。

# unit suite (respx-mocked api.github.com, no real network touched)
python -m pytest -q

# handshake check -- prints every registered tool name
python scripts/list_tools.py

# real-network read smoke (get_repo against a stable public repo;
# no write smoke exists anywhere in this suite -- see safety rails above)
GITHUB_MCP_LIVE=1 python -m pytest -q -k live_get_repo

安装

pip install -r requirements.txt   # or: pip install .
# deps: fastmcp==3.4.2, httpx==0.28.1
# test-only: pytest==9.0.3, respx==0.23.1

设置 / 连接

1. 在 Python 3.12+ 环境中运行 pip install -r requirements.txt。
2. （可选）生成一个细粒度 PAT，并将其权限范围限定为你希望获得读写权限的仓库（Issues：读取/写入，Pull requests：读取/写入，Contents：读取即可满足 v1 的要求）。读取工具完全无需令牌——它们会使用 GitHub 未经身份验证的每小时 60 次请求限额。
3. 添加到 MCP 主机配置中（例如 ~/.claude.json）：

{
  "mcpServers": {
    "github-mcp": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["C:\\Users\\<you>\\projects\\github-mcp\\run_server.py"],
      "env": {
        "GITHUB_TOKEN": "your-fine-grained-pat-here"
        // GITHUB_MCP_ENABLE_WRITE intentionally absent -- write stays off
        // until you deliberately opt in per-deployment.
      }
    }
  }
}

4. 要为某个部署启用写入工具，请在对应条目的 env 块中添加 "GITHUB_MCP_ENABLE_WRITE": "1"。这是注册时由运营人员作出的决定，而非代码更改。

在 ~/.claude.json 中注册为 github-mcp（stdio、系统 Python312，始终启用 read 组，env 中不包含 write 组，即关闭）。

商业支持

由 Jaimen Bell 维护。如需生产环境的 MCP 集成、定制服务或 Agent 可靠性方面的工作，请参阅 jaimenbell.dev。

正在构建自己的 MCP 服务？MCP Starter Kit 提供模板、构建指南，以及发布此服务过程中积累的打包经验。

mcp-name: io.github.jaimenbell/github-mcp