github-mcp-proxy

一个运行在 Cloudflare Workers 上的自托管 GitHub MCP 服务器，专为个人/小型团队设计，为 AI 代理提供基于存储库的防护机制。

任何支持 MCP 的代理（Claude、Codex、ChatGPT、Cursor、Cline 等）都可以接入，并能严格控制其可以访问哪些存储库以及如何操作。

[!WARNING] 如果您需要安全或稳定性，请使用 官方 GitHub MCP 服务器。 请随意分叉；一旦分叉，安全问题由您自行负责。

为什么选择它

通用的 GitHub 令牌会赋予代理完整的账户访问权限。此服务器缩小了该权限范围：

• 存储库级权限级别 — read / issues / full

• 分支保护 — 新分支必须匹配前缀（默认为 claude/）；main/master 分支永远不可写入

• 提交信息策略 — 强制执行 Conventional Commits 规范，并在服务器端进行验证

• 标签白名单 — 每个存储库的 allowedLabels；服务器永远不会在 GitHub 上自动创建标签

• 禁止路径 — .github/workflows/** 始终被阻止

• 审计追踪 — 每次写入操作都会自动附加 Signed-off-by / Assisted-by 尾注或页脚，以标识代理和模型

Related MCP server: Kontrol

架构

 MCP agent ──(Streamable HTTP + OAuth)──▶ Cloudflare Worker
                                              │
                                              ├── workers-oauth-provider  (OAuth 2.1 server to MCP clients)
                                              ├── GitHub OAuth            (OAuth client to github.com)
                                              ├── KV                      (session tokens)
                                              ├── Durable Object          (MCP agent state)
                                              └── Octokit                 (GitHub REST)

配置 (ghmcp.config.ts) 在部署时与 Worker 一起打包 — 无需运行时 KV 读取，通过 satisfies 进行类型检查。

快速开始

git clone <your-fork>
cd kz-github-mcp
npm install
cp ghmcp.config.sample.ts ghmcp.config.ts   # edit: repos you want to expose
cp wrangler.sample.jsonc wrangler.jsonc      # edit: KV id + worker name
cp .env.example .env                         # edit: for local dev only

创建一个 GitHub OAuth App（主页 = https://<worker>.<subdomain>.workers.dev，回调 = /callback），然后：

wrangler kv namespace create "OAUTH_KV"      # add the id to wrangler.jsonc
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY    # openssl rand -hex 32
npm run deploy

本地开发：使用指向 http://localhost:8788 的第二个 OAuth App 进行相同的流程，将凭据放入 .env，然后运行 npm run dev。

持续部署（可选）

.github/workflows/deploy.yml 会在每次推送到 main 时部署到 Cloudflare。在 GitHub 设置 → Secrets and variables → Actions 中设置两个存储库密钥：

GitHub OAuth 凭据 (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY) 作为 Wrangler 密钥存储在 Worker 本身，而不是 GitHub Actions 中 — 您只需使用 wrangler secret put 设置一次即可。

有关其工作原理，请参阅 docs/ARCHITECTURE.md；有关每个配置字段，请参阅 docs/CONFIG.md。

连接 AI 代理

Claude (claude.ai) — 设置 → 连接器 → 添加自定义连接器 → 粘贴 https://<worker>.<subdomain>.workers.dev/sse。

Claude Code / Codex / Cursor / Cline — 添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["mcp-remote", "https://<worker>.<subdomain>.workers.dev/sse"]
    }
  }
}

任何 MCP 主机 — 将其指向同一个 /sse 端点。OAuth 流程在首次连接时运行。

为了教导代理如何正确使用工具，请将其 SKILL.md 包含在系统提示词 / 项目说明 / 技能目录中。

工具

以 ghmcp_ 为前缀。每个工具都声明了最低权限级别；服务器会拒绝低于该级别的调用。

任何工具都可以通过配置中的 disabledTools 禁用。

验证

npm run validate-config

使用 gh CLI 确认 ghmcp.config.ts 中的每个存储库都存在，并且 allowedLabels 中的每个标签都在 GitHub 上存在。作为 prebuild 钩子自动运行，因此拼写错误会导致 npm run build 失败。

许可证

最初分叉自 cloudflare/ai/demos/remote-mcp-github-oauth。采用 MIT 许可证。

本工具采用 MIT 许可证。 — 请参阅 LICENSE。