github-mcp-server

GitHub MCP 服务文档

本文档介绍 GitHub MCP（Model Context Protocol）服务，包括工具和配置选项。

注意：此文件由 github-mcp-tools-report.md 工作流自动生成和更新。手动编辑可能会被覆盖。

上次更新：[由工作流填写]

概述

GitHub MCP 服务通过 Model Context Protocol 为 AI Agent 提供对 GitHub API 的程序化访问。它支持两种运行模式：

本地模式（基于 Docker）

• 在 GitHub Actions 运行器上作为 Docker 容器运行
• 使用 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量进行身份验证
• 通过 GITHUB_TOOLSETS 环境变量配置工具集
• 通过 GITHUB_READ_ONLY 环境变量支持只读模式

远程模式（托管）

• 连接到托管的 GitHub MCP 服务 https://api.githubcopilot.com/mcp/
• 在 HTTP 标头中使用 Bearer 令牌身份验证
• 通过 X-MCP-Readonly 标头支持只读模式
• 无需 Docker 容器

配置

基本配置

本地模式（Docker）：

tools:
  github:
    mode: "local"
    toolsets: [default]  # or [repos, issues, pull_requests]

远程模式（托管）：

tools:
  github:
    mode: "remote"
    toolsets: [default]  # or [repos, issues, pull_requests]

只读模式

要将 GitHub MCP 服务限制为只读操作：

tools:
  github:
    mode: "remote"
    read-only: true
    toolsets: [repos, issues]

自定义身份验证

使用自定义 GitHub 令牌代替默认令牌：

tools:
  github:
    mode: "remote"
    github-token: "${{ secrets.CUSTOM_GITHUB_PAT }}"
    toolsets: [repos, issues]

可用工具集

GitHub MCP 服务将工具组织成逻辑工具集。你可以启用特定工具集，使用 [default] 启用推荐的默认工具集，或使用 [all] 启用所有工具。

:::note[为什么要使用工具集？] 使用 allowed: 模式列出单个 GitHub 工具，不建议用于新的工作流。不同版本的 GitHub MCP 服务可能会更改单个工具的名称，但工具集提供稳定的 API。请始终使用 toolsets:。有关更新现有工作流的说明，请参阅从 Allowed 迁移到 Toolsets。 :::

:::tip[最佳实践] GitHub 工具请始终使用 toolsets:。 工具集具有以下优点：

• 稳定性：不同版本的 MCP 服务可能会更改工具名称，但工具集保持稳定
• 更好的组织方式：清晰地归类相关功能
• 完整功能：自动获取所有相关工具
• 减少冗余：配置更简洁
• 面向未来：新增工具时会自动包含 :::

推荐的默认工具集

未指定 toolsets: 时，默认启用以下工具集：

• context - 用户和环境上下文（强烈推荐）
• repos - 仓库管理
• issues - Issue 管理
• pull_requests - Pull Request 操作

注意：默认不包含 users 工具集，如有需要，必须显式指定。

所有可用工具集

工具集	说明	常用工具
context	用户和环境上下文	get_teams、get_team_members
repos	仓库管理	get_repository、get_file_contents、search_code、list_commits
issues	Issue 管理	issue_read、list_issues、create_issue、search_issues
pull_requests	Pull request 操作	pull_request_read、list_pull_requests、create_pull_request
actions	GitHub Actions/CI/CD	list_workflows、list_workflow_runs、download_workflow_run_artifact
code_security	代码扫描和安全	list_code_scanning_alerts ⚠️（始终包含 state: open 和 severity: critical,high）、get_code_scanning_alert
dependabot	依赖管理	Dependabot 警报和更新
discussions	GitHub 讨论	list_discussions、create_discussion
experiments	实验性功能	不稳定/预览版 API
gists	Gist 操作	create_gist、list_gists
labels	标签管理	get_label、list_labels、create_label
notifications	通知	list_notifications、mark_notifications_read
orgs	组织管理	get_organization、list_organizations
projects	GitHub Projects	项目看板操作
secret_protection	密钥扫描	密钥检测和管理
security_advisories	安全公告	公告创建和管理
stargazers	仓库星标	星标相关操作
users	用户资料	get_me ⚠️（见下方说明）、get_user、list_users
search	高级搜索	搜索仓库、代码和用户

:::caution[get_me 在集成令牌下会返回 403] 在 Agent 工作流中不建议使用 get_me。在 GitHub Actions 集成令牌下调用时（这是所有 gh-aw 运行的默认令牌），它会返回 HTTP 403。请勿调用 get_me 来确定 Agent 的身份。

标准身份来源：<github-context> 块会注入到每个工作流提示词的开头，其中包含 actor、repository、run_id 和其他上下文值。请始终从此处读取身份信息。 :::

按工具集划分的可用工具

本节将各个工具对应到所属工具集，帮助从 allowed: 迁移到 toolsets:。

Context 工具集

• get_teams - 列出用户所属的团队
• get_team_members - 列出特定团队的成员

Repos 工具集

• get_repository - 获取仓库信息
• get_file_contents - 读取仓库中的文件内容
• search_code - 跨仓库搜索代码
• list_commits - 列出仓库中的提交
• get_commit - 获取特定提交的详细信息
• get_latest_release - 获取最新版本
• list_releases - 列出所有版本

Issues 工具集

• issue_read - 读取 Issue 详情
• list_issues - 列出仓库中的 Issue
• create_issue - 创建新 Issue
• update_issue - 更新现有 Issue
• search_issues - 跨仓库搜索 Issue
• add_reaction - 对 Issue 或评论添加表情回应
• create_issue_comment - 向 Issue 添加评论

拉取请求工具集

• pull_request_read - 读取拉取请求详情
• list_pull_requests - 列出仓库中的拉取请求
• get_pull_request - 获取特定拉取请求的详情
• create_pull_request - 创建新的拉取请求
• search_pull_requests - 跨仓库搜索拉取请求

从工作流提示词/模板调用 list_pull_requests 时：

• 默认使用较小的分页大小（perPage: 10，除非有理由使用更小或更大的值）。
• 在 GitHub MCP 服务 ≥ 1.6.0 且支持 fields_param 功能时（Insiders 模式下会自动启用），传入 fields: [number, title, state, html_url]（或你需要的任意顶层字段），以减少响应大小。同一个 fields 参数也可用于 list_issues、search_issues、search_pull_requests、list_commits、list_releases 和 search_code。对于 get_file_contents，fields 仅能减少目录列表的大小；在决定是否读取文件之前，可使用 fields: [name, type, size, path] 检查文件元数据。
• 对文件使用 get_file_contents 之前，先通过 fields: [name, type, size, path] 列出其父目录。如果文件较大，或你只需要标题/章节，请使用受限摘录，例如带 HTTP range 的原始文件 URL 或其他可用的范围读取工具，而不是获取整个文件。
• 对于较旧的服务，如果已安装的 MCP 服务提供了 minimal_output: true 输入，请求时使用该参数（最小输出会删去大型 head/base 等非必要的嵌套字段）。
• 通过 mcp list-tools 或对应服务版本的工具文档，确认方法架构中支持的参数。

Actions 工具集

• list_workflows - 列出 GitHub Actions 工作流
• list_workflow_runs - 列出工作流运行记录
• get_workflow_run - 获取特定工作流运行记录的详情
• download_workflow_run_artifact - 下载工作流产物

代码安全工具集

• list_code_scanning_alerts - 列出代码扫描警报
• get_code_scanning_alert - 获取特定警报的详情
• create_code_scanning_alert - 创建代码扫描警报

从工作流提示词/模板调用 list_code_scanning_alerts 时，始终包含 state: open 和 severity: critical,high，以限制响应大小并避免载荷过大。

讨论工具集

• list_discussions - 列出仓库中的讨论
• create_discussion - 创建新讨论

标签工具集

• get_label - 获取标签详情
• list_labels - 列出仓库中的标签
• create_label - 创建新标签

用户工具集

• get_me - ⚠️ 不推荐 — 在集成令牌下会返回 HTTP 403。请使用 <github-context> 块（每个提示词开头都会提供）读取你的身份信息：actor、repository、run_id 等。
• get_user - 获取用户个人资料信息
• list_users - 列出用户

通知工具集

• list_notifications - 列出用户通知
• mark_notifications_read - 将通知标记为已读

组织工具集

• get_organization - 获取组织详情
• list_organizations - 列出组织

Gist 工具集

• create_gist - 创建新的 gist
• list_gists - 列出用户的 gist

身份验证详情

远程模式身份验证

远程模式使用 Bearer 令牌身份验证：

请求头：

• Authorization: Bearer <token> - 身份验证必需
• X-MCP-Readonly: true - 可选，启用只读模式

令牌来源：

• 默认：${{ secrets.GH_AW_GITHUB_TOKEN }} 或 ${{ secrets.GITHUB_TOKEN }}
• 自定义：通过 github-token 字段配置

本地模式身份验证

本地模式使用环境变量：

环境变量：

• GITHUB_PERSONAL_ACCESS_TOKEN - 身份验证必需
• GITHUB_READ_ONLY=1 - 可选，启用只读模式
• GITHUB_TOOLSETS=<comma-separated-list> - 可选，指定启用的工具集

最佳实践

工具集选择

1. 从默认设置开始：对于大多数工作流，推荐的默认工具集已能提供足够的功能
2. 启用特定工具集：仅在需要其特定功能时才启用其他工具集
3. 安全注意事项：注意写入操作；尽可能考虑使用只读模式
4. 性能：使用较少的工具集可以减少初始化时间和内存占用

令牌权限

请确保你的 GitHub 令牌具备所启用工具集所需的权限：

• repos 工具集：需要仓库读写权限
• issues 工具集：需要议题读写权限
• pull_requests 工具集：需要拉取请求读写权限
• actions 工具集：需要 Actions 读写权限
• discussions 工具集：需要讨论读写权限

远程模式与本地模式

适合使用远程模式的情况：

• 你希望更快地初始化（无需启动 Docker 容器）
• 你在可访问互联网的 GitHub Actions 环境中运行
• 你希望使用最新版本，而无需指定 Docker 镜像标签

适合使用本地模式的情况：

• 你需要特定版本的 MCP 服务
• 你希望使用自定义参数
• 你在无法访问互联网的环境中运行
• 你希望使用 MCP 服务的本地构建版本进行测试

从 Allowed 迁移到 Toolsets

如果你现有的工作流使用 allowed: 模式，我们建议迁移到 toolsets:，以提高可维护性和稳定性。不同版本的 MCP 服务可能会更改单个工具的名称，但工具集提供稳定的 API，不会导致你的工作流失效。

迁移示例

使用 allowed:（不推荐）：

tools:
  github:
    allowed:
      - get_repository
      - get_file_contents
      - list_commits
      - list_issues
      - create_issue
      - update_issue

使用 toolsets:（推荐）：

tools:
  github:
    toolsets: [repos, issues]

工具到工具集的映射

使用此表确定你需要的工具所属的工具集：

allowed: 工具	迁移到 toolsets:
get_me ⚠️（不推荐 — 会返回 403；请改用 <github-context>）	users
get_teams, get_team_members	context
get_repository, get_file_contents, search_code, list_commits	repos
issue_read, list_issues, create_issue, update_issue, search_issues	issues
pull_request_read, list_pull_requests, create_pull_request	pull_requests
list_workflows, list_workflow_runs, get_workflow_run	actions
list_code_scanning_alerts ⚠️（始终包含 state: open 和 severity: critical,high），get_code_scanning_alert	code_security
list_discussions, create_discussion	discussions
get_label, list_labels, create_label	labels
get_user, list_users	users
混合使用 repos/issues/PRs 工具	[default]
所有工具	[all]

快速迁移步骤

1. 确定正在使用的工具：检查当前的 allowed: 列表
2. 映射到工具集：使用上表查找对应的工具集
3. 替换配置：将 allowed: 改为 toolsets:
4. 测试：运行 gh aw mcp inspect <workflow>，验证工具是否可用
5. 编译：运行 gh aw compile，更新锁文件

在自定义 MCP 服务中使用 Allowed 模式

:::note[适用 allowed 的情况] allowed: 模式适用于：

• 自定义 MCP 服务（非 GitHub）
• 逐步迁移现有工作流
• 在工具集中对特定工具进行细粒度限制

对于 GitHub 工具，始终使用 toolsets:，而不是 allowed:。 :::

对于自定义 MCP 服务，仍可使用 allowed: 字段限制工具：

mcp-servers:
  notion:
    container: "mcp/notion"
    allowed: ["search_pages", "get_page"]  # Fine for custom MCP servers

对于 GitHub 工具，可以将 allowed: 与 toolsets: 结合使用，以进一步限制访问权限，但不建议在新工作流中采用此模式。

GitHub API 限制

并非所有 GitHub 数据都可通过 GitHub MCP 服务或 GitHub REST API 访问。设计工作流时，请留意以下限制，以免运行时静默失败或返回不完整的结果。

账单和费用数据

❌ 无法通过标准 API 权限访问：

• 每次运行的详细费用数据 — GitHub Actions 不会通过 REST API 提供每次工作流运行的账单费用。没有可用于获取特定工作流运行准确费用的端点。
• Actions 账单摘要 — 账单端点（例如 /orgs/{org}/settings/billing/actions）需要 admin:org 范围；actions:read 或默认的 GITHUB_TOKEN 均不会授予此权限。

⚠️ 建议账单或费用工作流时，请务必注明：

使用 actions:read 权限无法通过标准 GitHub API 访问详细的 GitHub Actions 账单和费用数据。除非明确配置具有 admin:org 范围的个人访问令牌，否则尝试读取每次运行的费用数据或账单摘要的工作流会静默失败或返回空结果。

✅ 费用报告的替代方案：

1. GitHub Actions 使用情况报告 — 从 GitHub 账单界面（Settings → Billing → Usage）下载使用情况报告，或通过账单 CSV 导出端点下载（需要具有 admin:org 范围的 PAT）。
2. 账单设置界面 — 引导用户前往 https://github.com/organizations/{org}/settings/billing，或个人账户的 https://github.com/settings/billing，手动查看费用数据。
3. 工作流运行元数据 — 使用 list_workflow_runs 和 get_workflow_run（可通过 actions 工具集使用）获取运行时长、状态和时间信息，但无法获取费用金额。
4. 第三方费用跟踪 — 集成使用预先授权 API 访问的第三方 CI 费用工具。

跨组织数据访问

❌ 未经明确授权无法访问：

• 工作流只能访问已授予所配置 GitHub 令牌访问权限的仓库和组织中的数据。
• 跨组织读取仓库需要具有目标组织访问权限的 PAT 或 GitHub App 令牌；默认的 GITHUB_TOKEN 仅限于当前仓库所属的组织。
• 未对其他组织明确授予 read:org 权限时，无法访问这些组织的成员身份和团队数据。

组织成员身份和私有数据

❌ 需要额外的权限范围：

• 组织成员列表 — 读取组织的私有成员信息需要 read:org 范围；默认的 GITHUB_TOKEN 只能查看公开成员信息。
• 私有仓库内容 — 只有在令牌具有明确的仓库访问权限时才能访问。
• 机密值 — GitHub Secrets 通过 API 只能写入；创建后无法读回其值。

速率限制

⚠️ 请留意 API 速率限制：

• GitHub REST API 实施速率限制（使用 PAT 进行身份验证的请求通常为每小时 5,000 次，使用 GITHUB_TOKEN 时限制更低）。
• 批量收集数据的工作流（例如，列出多个仓库中的所有工作流运行）可能会触发速率限制。请仔细设计工作流的分页方式，并避免不必要的请求。
• GraphQL API 会根据查询复杂度实施单独的速率限制。

故障排除

常见问题

问题：找不到工具或工具不可用

• 解决方案：检查是否使用了 allowed: 来限制工具。建议改用 toolsets:，以获取所有相关工具。
• 验证：运行 gh aw mcp inspect <workflow-name>，查看实际可用的工具。

问题：指定工具集后缺少功能

• 原因：使用的工具集范围过窄，未包含所有必需的工具
• 解决方案：添加其他工具集（例如，toolsets: [default, actions]），或使用 [all] 以获得完整访问权限

问题：使用 allowed: 列表的工作流冗长且难以维护

• 解决方案：按照上方的迁移指南，将配置迁移到 toolsets:

调试最佳实践

1. 从 [default] 工具集开始：大多数工作流使用默认工具集即可正常运行
2. 按需添加特定工具集：逐步添加 actions、discussions 等工具集
3. 使用 gh aw mcp inspect：验证实际可用的工具
4. 检查工具与工具集的映射关系：参考上方表格，找到合适的工具集

参考资料

• GitHub MCP 服务仓库
• 模型上下文协议规范
• GitHub Actions 文档