GitHub MCP Server

GitHub MCP 服务

用于 GitHub API 的 MCP 服务，可执行文件操作、管理仓库、搜索等。

Mission Squad 修改

• github pat 现在可按请求动态提供，无需通过环境变量设置，但仍会回退到环境变量。
• name：mcp-github

功能

• 自动创建分支：创建/更新文件或推送更改时，如果分支不存在，会自动创建
• 全面的错误处理：针对常见问题提供清晰的错误消息
• 保留 Git 历史记录：操作会保留正确的 Git 历史记录，不会强制推送
• 批量操作：支持单文件和多文件操作
• 高级搜索：支持搜索代码、议题/PR 和用户

工具

1. create_or_update_file

   • 在仓库中创建或更新单个文件
   • 输入：
     • owner（字符串）：仓库所有者（用户名或组织）
     • repo（字符串）：仓库名称
     • path（字符串）：创建/更新文件的路径
     • content（字符串）：文件内容
     • message（字符串）：提交消息
     • branch（字符串）：创建/更新文件所在的分支
     • sha（可选字符串）：被替换文件的 SHA（用于更新）
   • 返回：文件内容和提交详情

2. push_files

   • 在单次提交中推送多个文件
   • 输入：
     • owner（字符串）：仓库所有者
     • repo（字符串）：仓库名称
     • branch（字符串）：推送到的分支
     • files（数组）：要推送的文件，每个文件包含 path 和 content
     • message（字符串）：提交消息
   • 返回：已更新的分支引用

3. search_repositories

   • 搜索 GitHub 仓库
   • 输入：
     • query（字符串）：搜索查询
     • page（可选数字）：分页页码
     • perPage（可选数字）：每页结果数（最多 100）
   • 返回：仓库搜索结果

4. create_repository

   • 创建新的 GitHub 仓库
   • 输入：
     • name（字符串）：仓库名称
     • description（可选字符串）：仓库描述
     • private（可选布尔值）：仓库是否设为私有
     • autoInit（可选布尔值）：使用 README 初始化
   • 返回：已创建的仓库详情

5. get_file_contents

   • 获取文件或目录的内容
   • 输入：
     • owner（字符串）：仓库所有者
     • repo（字符串）：仓库名称
     • path（字符串）：文件/目录路径
     • branch（可选字符串）：要从中获取内容的分支
   • 返回：文件/目录内容

6. create_issue

   • 创建新议题
   • 输入：
     • owner（字符串）：仓库所有者
     • repo（字符串）：仓库名称
     • title（字符串）：议题标题
     • body（可选字符串）：议题描述
     • assignees（可选字符串数组）：要指派的用户名
     • labels（可选字符串数组）：要添加的标签
     • milestone（可选数字）：里程碑编号
   • 返回：已创建的议题详情

7. create_pull_request

   • 创建新的拉取请求
   • 输入：
     • owner（字符串）：仓库所有者
     • repo（字符串）：仓库名称
     • title（字符串）：PR 标题
     • body（可选字符串）：PR 描述
     • head（字符串）：包含更改的分支
     • base（字符串）：要合并到的分支
     • draft（可选布尔值）：创建为草稿 PR
     • maintainer_can_modify（可选布尔值）：允许维护者编辑
   • 返回：已创建的拉取请求详情

8. fork_repository

   • 复刻仓库
   • 输入：
     • owner（字符串）：仓库所有者
     • repo（字符串）：仓库名称
     • organization（可选字符串）：要复刻到的组织
   • 返回：已复刻的仓库详情

9. create_branch

   • 创建新分支
   • 输入：
     • owner (string)：仓库所有者
     • repo (string)：仓库名称
     • branch (string)：新分支名称
     • from_branch (optional string)：源分支（默认为仓库默认分支）
   • 返回：已创建的分支引用

10. list_issues

    • 列出并筛选仓库问题
    • 输入：
      • owner (string)：仓库所有者
      • repo (string)：仓库名称
      • state (optional string)：按状态筛选（'open'、'closed'、'all'）
      • labels (optional string[])：按标签筛选
      • sort (optional string)：按（'created'、'updated'、'comments'）排序
      • direction (optional string)：排序方向（'asc'、'desc'）
      • since (optional string)：按日期筛选（ISO 8601 时间戳）
      • page (optional number)：页码
      • per_page (optional number)：每页结果数
    • 返回：问题详情数组

11. update_issue

    • 更新现有问题
    • 输入：
      • owner (string)：仓库所有者
      • repo (string)：仓库名称
      • issue_number (number)：要更新的问题编号
      • title (optional string)：新标题
      • body (optional string)：新描述
      • state (optional string)：新状态（'open' 或 'closed'）
      • labels (optional string[])：新标签
      • assignees (optional string[])：新受理人
      • milestone (optional number)：新里程碑编号
    • 返回：已更新的问题详情

12. add_issue_comment

    • 为问题添加评论
    • 输入：
      • owner (string)：仓库所有者
      • repo (string)：仓库名称
      • issue_number (number)：要评论的问题编号
      • body (string)：评论内容
    • 返回：已创建的评论详情

13. search_code

    • 在 GitHub 仓库中搜索代码
    • 输入：
      • q (string)：使用 GitHub 代码搜索语法的搜索查询
      • sort (optional string)：排序字段（仅支持 'indexed'）
      • order (optional string)：排序顺序（'asc' 或 'desc'）
      • per_page (optional number)：每页结果数（最多 100）
      • page (optional number)：页码
    • 返回：包含仓库上下文的代码搜索结果

14. search_issues

    • 搜索问题和拉取请求
    • 输入：
      • q (string)：使用 GitHub 问题搜索语法的搜索查询
      • sort (optional string)：排序字段（comments、reactions、created 等）
      • order (optional string)：排序顺序（'asc' 或 'desc'）
      • per_page (optional number)：每页结果数（最多 100）
      • page (optional number)：页码
    • 返回：问题和拉取请求搜索结果

15. search_users

    • 搜索 GitHub 用户
    • 输入：
      • q (string)：使用 GitHub 用户搜索语法的搜索查询
      • sort (optional string)：排序字段（followers、repositories、joined）
      • order (optional string)：排序顺序（'asc' 或 'desc'）
      • per_page (optional number)：每页结果数（最多 100）
      • page (optional number)：页码
    • 返回：用户搜索结果

16. list_commits

• 获取仓库分支的提交记录
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • page (optional string)：页码
  • per_page (optional string)：每页记录数
  • sha (optional string)：分支名称
• 返回：提交记录列表

17. get_issue

• 获取仓库中某个问题的内容
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • issue_number (number)：要获取的问题编号
• 返回：GitHub Issue 对象及详情

18. get_pull_request

• 获取特定拉取请求的详细信息
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
• 返回：拉取请求详细信息，包括差异和审查状态

19. list_pull_requests

• 列出并筛选仓库的拉取请求
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • state (可选 string)：按状态筛选（'open'、'closed'、'all'）
  • head (可选 string)：按头部分支的用户/组织和分支筛选
  • base (可选 string)：按基础分支筛选
  • sort (可选 string)：按（'created'、'updated'、'popularity'、'long-running'）排序
  • direction (可选 string)：排序方向（'asc'、'desc'）
  • per_page (可选 number)：每页结果数（最多 100）
  • page (可选 number)：页码
• 返回：拉取请求详细信息数组

20. create_pull_request_review

• 在拉取请求上创建审查
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
  • body (string)：审查评论文本
  • event (string)：审查操作（'APPROVE'、'REQUEST_CHANGES'、'COMMENT'）
  • commit_id (可选 string)：要审查的提交 SHA
  • comments (可选 array)：针对特定行的评论，每条包含：
    • path (string)：文件路径
    • position (number)：差异中的行位置
    • body (string)：评论文本
• 返回：已创建的审查详细信息

21. merge_pull_request

• 合并拉取请求
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
  • commit_title (可选 string)：合并提交的标题
  • commit_message (可选 string)：合并提交的补充说明
  • merge_method (可选 string)：合并方式（'merge'、'squash'、'rebase'）
• 返回：合并结果详细信息

22. get_pull_request_files

• 获取拉取请求中已更改文件的列表
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
• 返回：已更改文件的数组，包含补丁和状态详细信息

23. get_pull_request_status

• 获取拉取请求所有状态检查的汇总状态
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
• 返回：汇总状态检查结果和各项检查的详细信息

24. update_pull_request_branch

• 使用基础分支的最新更改更新拉取请求分支（等同于 GitHub 的“Update branch”按钮）
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
  • expected_head_sha (可选 string)：拉取请求 HEAD 引用的预期 SHA
• 返回：分支更新成功时的提示消息

25. get_pull_request_comments

• 获取拉取请求上的审查评论
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
• 返回：拉取请求审查评论数组，包含评论文本、作者和在差异中的位置等详细信息

26. get_pull_request_reviews

• 获取拉取请求上的审查
• 输入：
  • owner (string)：仓库所有者
  • repo (string)：仓库名称
  • pull_number (number)：拉取请求编号
• 返回：拉取请求审查数组，包含审查状态（APPROVED、CHANGES_REQUESTED 等）、审查者和审查正文等详细信息

Webhook 工具

此服务现在支持现有 github_pat 身份验证模式下可用的完整仓库和组织 Webhook REST 接口。

仓库 Webhook 工具

• list_repository_webhooks
• get_repository_webhook
• create_repository_webhook
• update_repository_webhook
• delete_repository_webhook
• get_repository_webhook_config
• update_repository_webhook_config
• ping_repository_webhook
• list_repository_webhook_deliveries
• get_repository_webhook_delivery
• redeliver_repository_webhook_delivery

组织 Webhook 工具

• list_organization_webhooks
• get_organization_webhook
• create_organization_webhook
• update_organization_webhook
• delete_organization_webhook
• get_organization_webhook_config
• update_organization_webhook_config
• ping_organization_webhook
• list_organization_webhook_deliveries
• get_organization_webhook_delivery
• redeliver_organization_webhook_delivery

权限

仓库 Webhook：

• 经典 PAT 通常需要 admin:repo_hook（或权限范围更广的 repo），才能创建、编辑、删除、ping 或重新投递。
• 细粒度 PAT 需要仓库 Webhooks 权限：执行列表/获取操作需要 read，执行创建/更新/删除/ping/重新投递操作需要 write。

组织 Webhook：

• 经典 PAT 需要 admin:org_hook。
• 细粒度 PAT 需要组织 Webhooks 权限：执行列表/获取操作需要 read，执行创建/更新/删除/ping/重新投递操作需要 write。

使用说明

• 创建和更新 Webhook 的工具会在内部将 name 硬编码为 "web"，这是 GitHub 的要求。
• 仓库 Webhook 配置支持 url、content_type、secret 和 insecure_ssl。
• 组织 Webhook 配置除了支持上述字段外，还支持可选的 username 和 password，用于基本身份验证。
• GitHub 强烈建议设置 Webhook secret，并在接收服务上验证投递签名。
• insecure_ssl: "1" 会禁用证书验证，不建议使用。

调试流程

• 创建或更新后，使用 ping_*_webhook 触发一次测试投递。
• 使用 list_*_webhook_deliveries 检查最近的投递尝试。
• 使用 get_*_webhook_delivery 检查请求负载、标头以及 GitHub 捕获的响应。
• 使用 redeliver_*_webhook_delivery 重放失败或过期的投递。

不在范围内

• 此服务不实现用于接收 Webhook 投递的入站 HTTP 接收器。
• 此服务不会为你的 Webhook 端点执行投递签名验证。
• 此阶段不包含 GitHub App Webhook 端点，因为这些 API 需要基于 JWT 的应用身份验证，而非 PAT。

搜索查询语法

代码搜索

• language:javascript：按编程语言搜索
• repo:owner/name：在指定仓库中搜索
• path:app/src：在指定路径中搜索
• extension:js：按文件扩展名搜索
• 示例：q: "import express" language:typescript path:src/

Issues 搜索

• is:issue 或 is:pr：按类型筛选
• is:open 或 is:closed：按状态筛选
• label:bug：按标签搜索
• author:username：按作者搜索
• 示例：q: "memory leak" is:issue is:open label:bug

用户搜索

• type:user 或 type:org：按账户类型筛选
• followers:>1000：按关注者数量筛选
• location:London：按所在地搜索
• 示例：q: "fullstack developer" location:London followers:>100

如需了解详细的搜索语法，请参阅 GitHub 的搜索文档。

设置

个人访问令牌

创建 GitHub 个人访问令牌，并授予相应权限：

• 前往 个人访问令牌（位于 GitHub Settings > Developer settings）
• 选择此令牌可访问的仓库（Public、All 或 Select）
• 创建具有 repo 范围（“完全控制私有仓库”）的令牌
  • 或者，如果只使用公共仓库，则仅选择 public_repo 范围
• 复制生成的令牌

在 Claude Desktop 中使用

要在 Claude Desktop 中使用此服务，请将以下内容添加到 claude_desktop_config.json：

Docker

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "mcp/github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

构建

Docker 构建：

docker build -t mcp/github -f src/github/Dockerfile .

许可证

此 MCP 服务采用 MIT License 许可。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT License 的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。