Self-hosted GitHub MCP server

github-mcp

可自托管的 GitHub MCP 服务。使用个人访问令牌进行身份验证，通过 stdio 传输，与传输方式无关，因此可与 Claude Code（任何账户）、Codex CLI、Cursor 或任何兼容 MCP 的客户端配合使用。无需依赖 claude.ai OAuth。

基于 FastMCP 使用 Python 编写。安装方式与其他社区 Python MCP 服务相同。

为什么开发此项目

官方的 github/github-mcp-server（Go，60 多种工具）非常出色，适合需要包含各种功能、且与单一 Agent 平台身份验证流程绑定的服务。此项目面向以下使用者：

• 在多个 Claude 账户、Codex CLI、Cursor 或其他 MCP 客户端之间切换，并希望所有客户端使用相同的 GitHub 身份验证方式。
• 希望工具范围精简且经过审计，专注于 PR、仓库文件和 Dependabot 操作。
• 希望使用 Python 安装，并与其他 MCP 服务一同运行。

如果以上都不适用，请改用 github/github-mcp-server，这是更合适的选择。

工具范围（v0.1.0）

未来版本将扩展支持：工作流、发布、问题、规则集、密钥扫描警报、分支保护和仓库设置。

密钥安全（请先阅读）

v0.1.1+ 默认从 macOS 钥匙串读取 PAT。 非 macOS 环境和 CI 仍支持回退到环境变量，但推荐使用钥匙串方式，因为密钥不会进入 argv 或进程环境变量，因此不会被 ps aux、pgrep -fl、lsof、/proc/<pid>/environ、崩溃转储、CI 日志、调试器或任何运行内省命令的 LLM Agent 获取。

# One-time setup (macOS):
security add-generic-password -s github-mcp -a "$USER" -w "<your-fine-grained-PAT>"

# Update later (e.g. after rotation):
security delete-generic-password -s github-mcp -a "$USER" 2>/dev/null
security add-generic-password -s github-mcp -a "$USER" -w "<new-PAT>"

请勿使用内联 --env 安装：

# BAD — bakes the PAT into ~/.claude.json + every Claude child spawn's --mcp-config argv.
# Any pgrep / ps aux dumps it.
claude mcp add github --scope user --env GITHUB_TOKEN=github_pat_... -- <command>

# GOOD — no --env block. The server reads from Keychain at call time.
claude mcp add github --scope user -- <command>

PR/事件溯源：此安全路径于 2026-05-19 添加，此前一次 pgrep -fl chrome-devtools-mcp 操作将包含 PAT 的 claude 进程信息转储到了会话记录中。请参阅 adelaidasofia/github-mcp 钥匙串迁移（待 PR 合并后添加链接）。

在非 macOS 环境中，请回退到环境变量：

export GITHUB_TOKEN=<your-PAT>   # set in shell rc, NOT in argv

v0.1 工具范围所需的最低权限：Contents 读写、Pull requests 读写、Dependabot 读取。

安装

打开 Claude Code，然后粘贴：

/plugin marketplace add adelaidasofia/github-mcp
/plugin install github-mcp@github-mcp

git clone https://github.com/adelaidasofia/github-mcp ~/.claude/github-mcp
cd ~/.claude/github-mcp
uv tool install --editable .

cd ~/.claude/github-mcp
uv run github-mcp

服务器会按以下优先级从环境变量中读取 GitHub PAT：

1. GITHUB_TOKEN
2. GH_TOKEN

建议使用细粒度令牌。

权限范围矩阵

v0.1 最低要求：Metadata + Contents（读／写）+ Pull requests（读／写）+ Dependabot alerts（读）即可使用此版本中的所有工具。

面向未来：现在授予表中的全部权限，意味着新增 MCP 工具时无需轮换 PAT。这相当于在细粒度 PAT 界面中勾选“所有仓库权限”。权衡之处在于：令牌泄露时影响范围更广。对于存储在启用了 FileVault 加密的笔记本上的个人开发令牌，这样做是合理的；对于共享或生产部署，请重新评估。

MCP 会通过 health_check 检查权限范围——完成配置后调用它，以确认令牌实际拥有的权限。

可选：使用 GITHUB_API_BASE 配置 GitHub Enterprise Server。默认值为 https://api.github.com。

接入 MCP 客户端

Claude Code

添加到 ~/.claude/.mcp.json（或项目根目录中的任意 .mcp.json）：

{
  "mcpServers": {
    "github": {
      "command": "uv",
      "args": ["run", "--project", "/Users/<you>/.claude/github-mcp", "github-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.github]
command = "uv"
args = ["run", "--project", "/Users/<you>/.claude/github-mcp", "github-mcp"]

[mcp_servers.github.env]
GITHUB_TOKEN = "${GITHUB_TOKEN}"

Cursor

~/.cursor/mcp.json 使用与 Claude Code 相同的格式。环境变量配置块也相同。

其他兼容 MCP 的客户端

将其配置为启动 github-mcp 命令并通过标准输入／输出传输数据。该服务通过标准输入／输出使用标准 MCP 协议进行通信。

验证

GITHUB_TOKEN=ghp_yourpat uv run github-mcp

服务器会等待从标准输入接收 MCP 通信。在另一个 shell 中，通过客户端调用 health_check 进行验证。

测试

uv pip install -e ".[dev]"
uv run pytest tests/ -v

遥测

此插件会在某台机器上的 Claude Code 会话中首次加载时，向 myceliumai.co 发送一条匿名安装信号。

发送的内容：

• 插件名称（例如 slack-mcp）
• 插件版本（例如 0.1.0）

不会发送的内容：

• 不会发送用户标识符、姓名、电子邮件、令牌或 API 密钥
• 不会发送文件路径、消息内容或任何工作相关信息
• 去重处理后不会存储 IP 地址

**原因：**帮助维护者了解大家实际安装了哪些插件，从而将精力投入到有人使用的插件上。

**选择退出：**在启动 Claude Code 前设置环境变量 MYCELIUM_NO_PING=1。钩子将完全跳过网络调用。已发送过信号的安装会在 ~/.mycelium/onboarded-<plugin> 留下一个标记文件——如果要重置状态，请将其删除。

许可证

MIT。