Claude GitHub MCP

捷桥mcp


一个生产就绪的MCP（模型上下文协议）网桥服务器，用于连接 克劳德聊天 （克劳德·艾） 任何GitHub存储库.Claude可以直接从对话中读取文件、编写代码、搜索代码、批量提交更改和管理问题，所有这些都可以通过使用Streamable HTTP传输和OAuth 2.0身份验证的自定义MCP连接器完成。

V2：多回购模式 --没有硬编码的仓库。克劳德通过 owner 和 repo 每次工具调用。使用Claude Project系统提示将Claude锁定到特定的仓库（请参见 项目范围界定 在......下面

建筑

  Claude Chat (claude.ai)
    ↕ MCP connector (Streamable HTTP + OAuth 2.0)
  MCP Bridge Server (your host) — multi-repo mode
    ↕ GitHub REST API (Octokit)
  Any GitHub Repo (files + Issues)

服务器公开了一个 /mcp 通过Streamable HTTP传输MCP协议的端点。Claude.ai使用OAuth 2.0客户端凭据连接到此端点，发现可用工具，并在对话中根据需要调用它们。在V2中，服务器与仓库无关——Claude指定了目标 owner/repo 每次工具调用。

先决条件

• A. GitHub账号 使用您希望Claude管理的存储库
• A. Claude Pro、Max或团队计划 （定制MCP连接器需要付费计划）
• 一个可以运行Node.js服务器（Replit、Railway、Render、VPS等）的托管平台

安装说明

1.分叉或克隆此仓库

git clone https://github.com/ioTus/gitbridge-mcp.git
cd gitbridge-mcp
npm install

2.创建GitHub个人访问令牌（PAT）

1. 首选 GitHub→ 设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
2. 点击 生成新令牌（经典）
3. 给它一个描述性的名字（例如。 claude-mcp-bridge)
4. 选择 repo 范围（文件读/写、问题和存储库元数据）和 project 范围（项目V2板访问）
5. 点击 生成令牌 并复制该值——您将不会再看到它

3.生成OAuth凭据

这些凭据使用行业标准OAuth 2.0保护您的MCP端点：

# Generate a random Client ID and Client Secret
OAUTH_CLIENT_ID=$(openssl rand -hex 16)
OAUTH_CLIENT_SECRET=$(openssl rand -hex 32)
echo "OAUTH_CLIENT_ID=$OAUTH_CLIENT_ID"
echo "OAUTH_CLIENT_SECRET=$OAUTH_CLIENT_SECRET"

保存这两个值——在下一步和配置Claude时都需要它们。

4.设置环境变量

创建一个 .env 在托管平台的secrets/environment面板中文件或设置这些内容：

服务器将 拒绝开始 如果缺少任何必需的变量。这三种都是强制性的——没有未经身份验证的模式。

V2注释： GITHUB_OWNER 和 GITHUB_REPO 不再使用环境变量。目标存储库是通过每次工具调用指定的 owner 和 repo 参数。

5.部署/运行

关于回复： 单击运行。服务器自动启动。

本地或其他平台：

npm run dev

服务器将从端口5000（或您设置的任何端口）启动 PORT ）。您应该看到：

[MCP] OAuth 2.0 Client Credentials authentication is ENABLED
[MCP] Token endpoint: /oauth/token
[MCP] MCP endpoint: /mcp

6.连接克劳德

1. 首选 claude.ai→ 设置→ 集成→ 添加更多→ 定制MCP连接器
2. 请输入您的服务器URL： https://your-server-url.example.com/mcp
3. 打开 高级设置
4. 集 客户端ID 到你的 OAUTH_CLIENT_ID 价值
5. 集 客户端密钥 到你的 OAUTH_CLIENT_SECRET 价值
6. 集 授权URL 到 https://your-server-url.example.com/oauth/token
7. Claude将使用客户端凭据流进行身份验证，并自动发现所有工具

7.开始使用它

在任何克劳德的谈话中，你现在都可以说这样的话：

• *“从仓库读取src/index.ts文件”*
• *“使用debounce函数创建一个名为utils/helpers.ts的新文件”*
• *“列出所有标记为‘bug’的未解决问题”*
• *“创建一个标题为“添加暗模式支持”的问题，并附上描述”*

Claude将使用MCP工具直接与您的GitHub仓库交互。

安全

身份验证的工作原理

服务器实现 OAuth 2.0客户端凭据流 （RFC 6749）。当Claude.ai连接时：

1. 克劳德发帖至 /oauth/token 随着 client_id, client_secret，以及 grant_type=client_credentials
2. 服务器根据验证凭据 OAUTH_CLIENT_ID 和 OAUTH_CLIENT_SECRET
3. 如果有效，服务器将返回一个签名的JWT访问令牌（HMAC-SHA256，1小时后过期）
4. 克劳德将JWT作为 Bearer 令牌在 Authorization 所有MCP请求的标头
5. 服务器验证每个请求的JWT签名和过期时间
6. 当令牌过期时，Claude会自动重新进行身份验证

URL中没有嵌入任何秘密。所有身份验证都是通过标准HTTP标头进行的。

信任模型

• 您的OAuth凭据控制谁可以连接到MCP服务器
• 你的 GITHUB_PERSONAL_ACCESS_TOKEN 控制服务器在GitHub上可以做什么——PAT的作用域决定了Claude可以访问哪些存储库
• 任何拥有OAuth凭据的人都可以通过服务器使用GitHub PAT的权限
• 在多仓库模式下，Claude可以访问PAT有权访问的任何仓库——使用Claude Project系统提示来约束Claude的目标仓库（参见 项目范围界定)
• 将所有令牌和秘密视为机密——永远不要将其提交给版本控制

PAT范围最佳实践

您的GitHub PAT决定了 爆炸半径 --PAT可以访问的每个仓库都可以通过MCP网桥访问。为了将风险降至最低：

• 使用细粒度PAT （GitHub→ 设置→ 开发人员设置→ 细粒度令牌）尽可能地作用于特定的存储库。这将Claude限制为仅允许您明确授予访问权限的存储库，即使有人获得了您的OAuth凭据。
• 使用经典PAT repo + project 范围 如果细粒度令牌不支持您的用例。避免授予 admin, delete_repo或其他高架镜。
• 为每个用例创建单独的PAT --例如，一个用于你的个人项目，另一个用于工作仓库。如果需要，运行单独的网桥实例。
• 定期轮换PAT 并撤销任何不再使用的。

建议

• 服务器 需要 OAUTH_CLIENT_ID 和 OAUTH_CLIENT_SECRET --没有他们，一切都不会开始
• 集 ALLOWED_REPOS 限制哪些存储库可以通过网桥访问（例如。 ALLOWED_REPOS=ioTus/my-repo,ioTus/other-repo)
• 使用具有所需最小范围的GitHub PAT(repo + project)
• 定期轮换凭据
• 定期在GitHub上审核PAT的存储库访问权限→ 设置→ 开发人员设置→ 个人访问令牌

工具

所有工具均接受 owner 和 repo 根据所需参数。编写工具在响应前加上前缀 ✅ Writing to: {owner}/{repo}.

文件工具

问题工具

搜索和历史

分行管理

高级文件操作

回购管理

项目委员会

API终点

项目范围界定

由于V2使用多仓库模式（没有硬编码 GITHUB_OWNER/GITHUB_REPO)，你应该使用 Claude项目系统提示 以控制Claude的目标存储库。根据您的工作流程，有两种方法：

选项A：每个回购一个项目（推荐）

最简单、最安全的方法。为每个存储库创建一个单独的Claude项目，并使用一个系统提示将Claude锁定到该特定的存储库。

You are working exclusively in the GitHub repository:
owner=YOUR_USERNAME repo=YOUR_REPO

Pass these values on every tool call to the GitHub MCP bridge.
Never write to any other repository regardless of what the user asks.
If asked to work in a different repo, tell the user to switch to
the appropriate Claude Project for that repository.

## Session Startup (do this every conversation)

1. Read `IME.md` at the repo root — this is the spoke bootstrap
   with repo identity and tool reference. Follow its hub pointer
   to `ioTus/ime` for universal rules.
2. Read `IME-AGENTS.md` and `IME-AGENTS-replit.md` — these define the
   multi-agent collaboration workflow.
3. Call `list_files` to confirm connectivity.
4. Check `IME-docs/plans/` for active plans (status: executing).
5. Check open Issues with `list_issues`.
6. Ask the user what they want to work on.

## Critical Rules (always active, even before reading IME.md)

- NEVER commit a file without showing the user the content first
  and getting explicit approval.
- NEVER overwrite an existing file without reading the current
  version first.
- NEVER delete a file without the user confirming the specific
  file path.
- For all other rules, defer to IME.md and IME-AGENTS.md in the repo.

## Your Role

You are the PM and strategist for this project. You write plans,
specs, documentation, and issues. You do not own implementation
code — that belongs to Replit Agent. Propose technical ideas inside
plan docs and issue bodies, not as committed code files in Replit
Agent's protected directories (server/, client/, script/).

See IME.md for the spoke context and IME-AGENTS-replit.md
for workspace boundaries.

## Connection Failure Protocol

This lives here — not on the server — because when the bridge
is down, server-side instructions are unreachable.

### Degraded Mode (activate immediately on failure)

When any MCP tool call fails:

1. Announce: "Bridge is down. Switching to degraded mode —
   all work will be staged here and pushed when it's back."
2. Draft all files/issues exactly as they'd appear in the repo.
   Tag each with file path + commit message, or issue title + labels.
3. Maintain a queue manifest:
   | # | Type | Path / Title | Status |
   |---|------|-------------|--------|
4. Silent-retry bridge ONCE per new user message.
5. Continue working. Zero productivity loss.

Never skip approval. Never spam retries. Never lose the queue.

### Diagnose (on request, or if user wants to troubleshoot)

If the user asks why the bridge is down or wants to fix it:
1. Classify: auth error (handshake/PAT), timeout (server asleep),
   connection refused (server down/URL wrong), 403 (PAT scopes),
   404 (bad path/repo), rate limit (wait/retry)
2. Try `list_files` to confirm systemic vs. isolated failure
3. Report: what failed, what it means, ONE recommended fix
   tailored to user's environment. Never a generic list.
4. Ask desktop or mobile BEFORE prescribing recovery steps.
   - Desktop: remove/re-add connector in Settings → Connectors.
     Check deployment is awake. Verify PAT not expired.
   - Mobile: try claude.ai in mobile browser with "request
     desktop site" to access Connectors. If inaccessible →
     stay in degraded mode until desktop available.
   - Either: visit server URL in browser to confirm it responds.

### Reconnection (exiting degraded mode)

When any MCP call succeeds after a period of degraded mode:
1. Announce: "Bridge is back online."
2. Display the full queue manifest.
3. Get single user approval to push everything.
4. Execute: files via push_multiple_files, issues via create_issue.
5. Confirm each item pushed successfully.
6. Clear the queue. Resume normal operations.

建议大多数用户使用这种方法。每个项目都有明确的界限，没有交叉回购错误的风险。

选项B：一个项目，多个仓库（高级）

适用于在一次对话中跨多个存储库工作的高级用户。系统提示定义了Claude的角色，但没有锁定到特定的仓库。相反，每个回购都通过一个 IME.md 根目录下的文件。

You are a developer assistant with access to GitHub repositories via
the MCP bridge. You can work across multiple repos in a single session.

Before performing any operation on a repo, read its IME.md file
(if it exists) to pick up project-specific rules and context:
  call read_file with owner=OWNER repo=REPO path=IME.md

Always confirm the target owner/repo before any write operation.
When switching between repos, announce the switch clearly.

## Session Startup (do this every conversation)

1. Ask the user which repo(s) they want to work with.
2. Read `IME.md` from each target repo — this is the spoke bootstrap
   with repo identity and hub pointer. Follow the hub pointer for
   universal rules.
3. Read `IME-AGENTS.md` and `IME-AGENTS-replit.md` from each target repo
   (if they exist) for multi-agent collaboration context.
4. Call `list_files` on each repo to confirm connectivity.
5. Check `IME-docs/plans/` for active plans (status: executing).
6. Check open Issues with `list_issues`.
7. Ask the user what they want to work on.

## Critical Rules (always active, even before reading IME.md)

- NEVER commit a file without showing the user the content first
  and getting explicit approval.
- NEVER overwrite an existing file without reading the current
  version first.
- NEVER delete a file without the user confirming the specific
  file path.
- For all other rules, defer to IME.md and IME-AGENTS.md in each repo.

## Your Role

You are the PM and strategist for these projects. You write plans,
specs, documentation, and issues. You do not own implementation
code — that belongs to Replit Agent. Propose technical ideas inside
plan docs and issue bodies, not as committed code files in Replit
Agent's protected directories (server/, client/, script/).

See IME.md in each repo for the spoke context and
IME-AGENTS-replit.md for workspace boundaries.

## Connection Failure Protocol

This lives here — not on the server — because when the bridge
is down, server-side instructions are unreachable.

### Degraded Mode (activate immediately on failure)

When any MCP tool call fails:

1. Announce: "Bridge is down. Switching to degraded mode —
   all work will be staged here and pushed when it's back."
2. Draft all files/issues exactly as they'd appear in the repo.
   Tag each with file path + commit message, or issue title + labels.
3. Maintain a queue manifest:
   | # | Type | Path / Title | Status |
   |---|------|-------------|--------|
4. Silent-retry bridge ONCE per new user message.
5. Continue working. Zero productivity loss.

Never skip approval. Never spam retries. Never lose the queue.

### Diagnose (on request, or if user wants to troubleshoot)

If the user asks why the bridge is down or wants to fix it:
1. Classify: auth error (handshake/PAT), timeout (server asleep),
   connection refused (server down/URL wrong), 403 (PAT scopes),
   404 (bad path/repo), rate limit (wait/retry)
2. Try `list_files` to confirm systemic vs. isolated failure
3. Report: what failed, what it means, ONE recommended fix
   tailored to user's environment. Never a generic list.
4. Ask desktop or mobile BEFORE prescribing recovery steps.
   - Desktop: remove/re-add connector in Settings → Connectors.
     Check deployment is awake. Verify PAT not expired.
   - Mobile: try claude.ai in mobile browser with "request
     desktop site" to access Connectors. If inaccessible →
     stay in degraded mode until desktop available.
   - Either: visit server URL in browser to confirm it responds.

### Reconnection (exiting degraded mode)

When any MCP call succeeds after a period of degraded mode:
1. Announce: "Bridge is back online."
2. Display the full queue manifest.
3. Get single user approval to push everything.
4. Execute: files via push_multiple_files, issues via create_issue.
5. Confirm each item pushed successfully.
6. Clear the queue. Resume normal operations.

这种方法需要更多的纪律，但允许跨仓库工作流（例如，协调前端和后端仓库的更改）。每个写入工具响应包括 ✅ Writing to: {owner}/{repo} 因此，您始终可以验证目标。

仪表盘

服务器在根URL处包含一个web仪表板。未经身份验证的访问者只能看到服务器名称、版本和状态。使用OAuth凭据登录(OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET)查看：

• 设置Claude自定义MCP连接器的连接细节
• 活动MCP会话
• 带有相位指示器的完整工具注册表
• 架构图和设置说明

技术栈

• 运行时间： Node.js与TypeScript
• MCP-SDK： @modelcontextprotocol/sdk （流式HTTP+SSE传输）
• GitHub API： Octokit REST客户端
• 认证： 带有HMAC-SHA256签名JWT的OAuth 2.0客户端凭据
• 服务器： 快速
• 前端： React+Vite+顺风CSS+shadcn/ui

许可证

麻省理工学院