GitHub Dev MCP
by hrygo
README.md
# Gemini GitHub MCP Proxy
让 Gemini Web 与 Gemini 手机 App 直接读取代码、修改文件、提交 commit、创建 Draft PR、处理 Issue,不依赖 Gemini 执行 `gh`。
每个使用者部署自己的 Cloudflare Worker,并绑定自己的 GitHub PAT。不要把同一个 Worker 当作多人共享服务:那会让所有人以同一个 GitHub 身份操作。
[English quick start](README.en.md)
## 能做什么
- 读取私有和公开仓库文件、commit、branch、Issue 与 PR
- 创建分支、提交或更新文件
- 创建与更新 Draft PR
- 读取、创建、更新 Issue,添加评论
- 执行 PR 审阅和行内评论
- Gemini 网页端连接一次,同一 Google 账号的移动端复用同一 Connector
默认工具白名单不包含 `delete_file`、`merge_pull_request`、`create_repository`、`fork_repository`。合并和删除应由人工或其他受控 agent 完成。
## 快速开始
### 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. 部署
```bash
npx wrangler login
npx gemini-github-mcp-proxy setup
```
也可全局安装:
```bash
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
成功后终端会显示:
```text
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` 不会可靠绑定工具。
## 推荐用法
先读后写:
```text
@GitHub Dev MCP 读取 owner/repo 和相关 Issue。
先分析现状并给出修改计划,不要写文件。
```
确认后实施:
```text
@GitHub Dev MCP 按已确认方案创建新分支,修改文件并提交。
创建 Draft PR,说明变更、验证和风险。不要合并。
```
Issue 协作:
```text
@GitHub Dev MCP 读取 Issue #123,在同一 Issue 回复结论和对应 Draft PR。
```
Gemini 没有本地 shell 和文件系统;提交后可让 GitHub Actions、Codex 或其他 code agent 接管测试和继续修复。
## 常用命令
```bash
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 # 只重新部署当前代码
```
指定其他部署地址验收:
```bash
npx gemini-github-mcp-proxy verify --url https://example.workers.dev
```
## 分享给朋友
朋友直接从 npm 安装,不需要下载源码。让每个人使用自己的 Cloudflare 账号和 GitHub PAT:
```bash
npx gemini-github-mcp-proxy setup
```
或:
```bash
npm install --global gemini-github-mcp-proxy
gemini-github-mcp setup
```
不要把以下内容发给别人:
- Cloudflare Secret
- GitHub PAT
- 授权 PIN
- 你已授权的 Connector URL,除非你明确允许对方使用你的 GitHub 身份
## 工作原理
```text
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](SECURITY.md)。
## 成本
个人使用 Cloudflare Workers Free 即可。截至 2026-11-22,官方免费额度为每天 100,000 次请求、每次 10ms CPU。[Cloudflare Workers Pricing](https://developers.cloudflare.com/workers/platform/pricing/) 与 [Limits](https://developers.cloudflare.com/workers/platform/limits/) 可能变化,启用付费产品或高流量前请重新核对。
## 排障
常见问题见 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)。优先运行:
```bash
npx gemini-github-mcp-proxy verify
npx wrangler deployments status
```
## 开发
```bash
npm install
npm run check
npm run dev
```
测试覆盖 OAuth/DCR、鉴权、工具白名单、JSON/SSE 文件正文转换和部署辅助函数。
## 参考
- [Google:连接和管理自定义 Gemini App](https://support.google.com/gemini/answer/17209137)
- [GitHub Remote MCP Server 配置](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md)
- [GitHub MCP:Gemini DCR/refresh 兼容问题](https://github.com/github/github-mcp-server/issues/3519)
- [GitHub MCP:EmbeddedResource 文件正文问题](https://github.com/github/github-mcp-server/issues/3189)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues