Skip to main content
Glama
GitHub Dev MCP

GitHub Dev MCP

by hrygo

Gemini GitHub MCP Proxy

让 Gemini Web 与 Gemini 手机 App 直接读取代码、修改文件、提交 commit、创建 Draft PR、处理 Issue,不依赖 Gemini 执行 gh。

每个使用者部署自己的 Cloudflare Worker,并绑定自己的 GitHub PAT。不要把同一个 Worker 当作多人共享服务:那会让所有人以同一个 GitHub 身份操作。

English quick start

能做什么

  • 读取私有和公开仓库文件、commit、branch、Issue 与 PR

  • 创建分支、提交或更新文件

  • 创建与更新 Draft PR

  • 读取、创建、更新 Issue,添加评论

  • 执行 PR 审阅和行内评论

  • Gemini 网页端连接一次,同一 Google 账号的移动端复用同一 Connector

默认工具白名单不包含 delete_file、merge_pull_request、create_repository、fork_repository。合并和删除应由人工或其他受控 agent 完成。

Related MCP server: GitHub Agent MCP Server

快速开始

1. 准备

  • Node.js 22 或更高版本

  • 一个 Cloudflare 账号

  • 一个 GitHub fine-grained PAT

在 GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens 创建 PAT,仅选择需要操作的仓库:

权限

级别

Metadata

Read

Contents

Read and write

Issues

Read and write

Pull requests

Read and write

2. 部署

npx wrangler login
npx gemini-github-mcp-proxy setup

也可全局安装:

npm install --global gemini-github-mcp-proxy
gemini-github-mcp setup

setup 会:

  1. 检查 Cloudflare 登录状态

  2. 安全读取并验证 GitHub PAT

  3. 生成随机 12 位授权 PIN 和签名密钥

  4. 部署 Worker

  5. 一次上传三个 Cloudflare Secrets

  6. 验收 OAuth、DCR、MCP 与鉴权端点

  7. 输出 Connector URL 和授权 PIN

成功后终端会显示:

Connector 名称:GitHub Dev MCP
MCP URL:https://gemini-github-mcp-proxy.<你的子域>.workers.dev/mcp
授权 PIN:<只显示一次>

PAT、授权 PIN 和签名密钥不会写入仓库或配置文件。非敏感部署信息保存在用户配置目录,供 gemini-github-mcp verify 使用。

接入 Gemini

  1. 在 Gemini Web 打开 设置 → 已连接的应用。

  2. 添加自定义 MCP App,名称填写 GitHub Dev MCP。

  3. MCP URL 使用 setup 输出的地址。

  4. Gemini 自动完成动态客户端注册;授权页输入部署时生成的 12 位 PIN。

  5. 手机端使用同一 Google 账号即可看到该 Connector。

每个新聊天必须:

  1. 输入 @。

  2. 从自动完成菜单明确选择 GitHub Dev MCP。

  3. 再输入任务。

只在正文中手写 @GitHub Dev MCP 不会可靠绑定工具。

推荐用法

先读后写:

@GitHub Dev MCP 读取 owner/repo 和相关 Issue。
先分析现状并给出修改计划,不要写文件。

确认后实施:

@GitHub Dev MCP 按已确认方案创建新分支,修改文件并提交。
创建 Draft PR,说明变更、验证和风险。不要合并。

Issue 协作:

@GitHub Dev MCP 读取 Issue #123,在同一 Issue 回复结论和对应 Draft PR。

Gemini 没有本地 shell 和文件系统;提交后可让 GitHub Actions、Codex 或其他 code agent 接管测试和继续修复。

常用命令

npx gemini-github-mcp-proxy setup            # 首次部署
npx gemini-github-mcp-proxy setup --rotate   # 强制轮换全部 Secrets
npx gemini-github-mcp-proxy verify           # 验收已部署 Worker
npm run check                                # 源码开发检查
npm run deploy                               # 只重新部署当前代码

指定其他部署地址验收:

npx gemini-github-mcp-proxy verify --url https://example.workers.dev

分享给朋友

朋友直接从 npm 安装,不需要下载源码。让每个人使用自己的 Cloudflare 账号和 GitHub PAT:

npx gemini-github-mcp-proxy setup

或:

npm install --global gemini-github-mcp-proxy
gemini-github-mcp setup

不要把以下内容发给别人:

  • Cloudflare Secret

  • GitHub PAT

  • 授权 PIN

  • 你已授权的 Connector URL,除非你明确允许对方使用你的 GitHub 身份

工作原理

Gemini Web / Mobile
        │ OAuth 2.1 + PKCE + DCR
        ▼
Cloudflare Worker
  ├─ 验证 Bearer token
  ├─ 注入 GitHub PAT
  ├─ 限制 MCP 工具
  └─ 修正 EmbeddedResource 文件正文
        │
        ▼
GitHub 官方 Remote MCP
        │
        ▼
GitHub API

需要 Worker 的原因:

  • GitHub Remote MCP 当前未完整满足 Gemini 所需的 DCR 与刷新令牌组合。

  • Gemini 会丢弃 GitHub 文件工具返回的 EmbeddedResource,只剩 SHA 状态文本。

  • PAT 不能安全地交给 Gemini 或移动端浏览器。

  • 集中工具白名单比直接暴露 GitHub 全部 MCP 写能力更可控。

安全

  • 授权 PIN 为随机 12 位数字,只在 setup 中显示一次。

  • ADMIN_PIN、SIGNING_SECRET、GITHUB_PAT 只存 Cloudflare Secret。

  • /mcp 必须携带签名有效的 Bearer token。

  • access token 与 refresh token 当前有效期均为 10 年;轮换 SIGNING_SECRET 会统一失效。

  • 断开 Gemini Connector 不等于立即吊销服务端令牌;高风险场景应同时轮换签名密钥和 GitHub PAT。

完整威胁模型与轮换步骤见 SECURITY.md。

成本

个人使用 Cloudflare Workers Free 即可。截至 2026-11-22,官方免费额度为每天 100,000 次请求、每次 10ms CPU。Cloudflare Workers Pricing 与 Limits 可能变化,启用付费产品或高流量前请重新核对。

排障

常见问题见 TROUBLESHOOTING.md。优先运行:

npx gemini-github-mcp-proxy verify
npx wrangler deployments status

开发

npm install
npm run check
npm run dev

测试覆盖 OAuth/DCR、鉴权、工具白名单、JSON/SSE 文件正文转换和部署辅助函数。

参考

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers