Klavis 中的 github_official:GitHub 官方 MCP Server 部署、工具集配置与安全模式实战指南
Klavis 中的 github_official:GitHub 官方 MCP Server 部署、工具集配置与安全模式实战指南
本篇围绕 mcp_servers/github_official/README.md 展开,系统讲解 GitHub 官方 MCP Server 的两种部署形态(远端托管服务与本地 Docker/二进制)、完整的工具集(toolsets)与工具(tools)配置体系,以及只读模式、Lockdown 模式、动态工具发现与工具描述国际化覆盖等安全与治理机制。读完之后,你可以为任意支持 MCP 的宿主应用(VS Code、Claude、Cursor 等)配置 GitHub 上下文接入,并基于源码验证理解工具过滤、只读约束和失败快速校验(fail fast)的底层实现。
项目定位与核心使用场景
GitHub MCP Server 将 AI 工具直接连接到 GitHub 平台,使 AI Agent、助手和聊天机器人能够通过自然语言交互完成以下任务(引自 README 的 Use Cases 一节):
- 仓库管理:浏览和查询代码、搜索文件、分析提交、理解任意可访问仓库的项目结构;
- Issue 与 PR 自动化:创建、更新和管理 Issue 与 Pull Request,让 AI 协助分诊缺陷、审查代码变更、维护项目看板;
- CI/CD 与流水线智能:监控 GitHub Actions 工作流运行、分析构建失败、管理发布,获取研发流水线洞察;
- 代码分析:查看安全发现、审查 Dependabot 告警、理解代码模式,获得代码库综合洞察;
- 团队协作:访问讨论区、管理通知、分析团队活动,简化团队流程。
该模块 fork 自 GitHub 官方仓库(README 首行注明 Forked from https://github.com/github/github-mcp-server),以 Go 语言实现,仓库内包含完整的命令行入口、工具实现包、HTTP 传输层、端到端测试与安装指南:入口在 cmd/github-mcp-server/main.go,工具实现集中在 pkg/github/,工具注册与过滤体系位于 pkg/inventory/。
两种部署形态:远端服务与本地服务
官方提供两条接入路径:Remote GitHub MCP Server(由 GitHub 托管,开箱即用)和 Local GitHub MCP Server(Docker 或源码编译,自托管)。如果 MCP 宿主不支持远端 MCP 服务器,应使用本地版本。
远端服务:前置条件与 VS Code 配置
前置条件:
- 支持远端服务器的 MCP 宿主(VS Code 1.101+、Claude Desktop、Cursor、Windsurf 等);
- 已启用适用的平台策略(见 docs/policies-and-governance.md)。
在 VS Code 中可一键安装,完成后切换 Agent 模式(位于 Copilot Chat 输入框旁)即可启动服务;请确保使用 VS Code 1.101 或更高版本以获得远端 MCP 与 OAuth 支持。手动配置时,向宿主配置的 MCP servers 中加入以下 JSON 之一:
使用 OAuth 认证:
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/"
}
}
}
使用 GitHub PAT(个人访问令牌)认证:
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${input:github_mcp_pat}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "github_mcp_pat",
"description": "GitHub Personal Access Token",
"password": true
}
]
}
其他 MCP 宿主的安装指南(相对仓库根目录):
- Copilot CLI:docs/installation-guides/install-copilot-cli.md
- 其他 IDE 中的 GitHub Copilot(JetBrains、Visual Studio、Eclipse、Xcode):install-other-copilot-ides.md
- Claude Desktop 与 Claude Code CLI:install-claude.md
- OpenAI Codex:install-codex.md
- Cursor:install-cursor.md
- Windsurf:install-windsurf.md
- Rovo Dev CLI:install-rovo-dev-cli.md
注意:每个 MCP 宿主应用若要支持 OAuth 远端访问,需要配置 GitHub App 或 OAuth App;任何支持远端 MCP 服务器的宿主都应支持使用 PAT 认证访问远端 GitHub 服务器。配置细节与支持程度因宿主而异。
远端服务完整配置(工具集、请求头、高级用法)见 docs/remote-server.md。
远端服务:Insiders 模式
远端服务器提供 insiders 版本,可提前体验新功能与实验性工具。两种开启方式等价:URL 路径使用 /mcp/insiders,或请求头 X-MCP-Insiders: true:
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/insiders"
}
}
}
{
"servers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"X-MCP-Insiders": "true"
}
}
}
}
远端服务:GitHub Enterprise
GitHub Enterprise Cloud(ghe.com,带数据驻留) 同样支持远端服务。以 https://octocorp.ghe.com 为例,使用 PAT 的配置为:
{
"proxima-github": {
"type": "http",
"url": "https://copilot-api.octocorp.ghe.com/mcp",
"headers": {
"Authorization": "Bearer ${input:github_mcp_pat}"
}
}
}
注意:在 VS Code 中使用 OAuth + GitHub Enterprise 时,还需将 VS Code 设置指向你的 GitHub Enterprise 实例完成认证。
GitHub Enterprise Server 不支持远端服务托管,应使用下文本地服务的配置方式,并通过 GITHUB_HOST 指定主机名。
本地 GitHub MCP Server:Docker、PAT 与源码构建
前置条件
- 安装 Docker(此处仅为概念依赖,实际操作以本机已装 Docker 为准);
- Docker 处于运行状态。镜像地址为
ghcr.io/github/github-mcp-server,是公开镜像;拉取报错时可能是过期令牌导致,可执行docker logout ghcr.io后重试; - 创建 GitHub 个人访问令牌(PAT)。MCP 服务器可调用大量 GitHub API,应按你对 AI 工具的信任程度授予权限。
PAT 安全处理(官方推荐做法):
- 将 PAT 存入环境变量:
export GITHUB_PAT=your_token_here,或写入.env文件; - 将
.env加入.gitignore防止误提交; - 在宿主配置中引用变量而非硬编码:CLI 方式
claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT,配置文件方式"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT" }; - 注意:环境变量支持因宿主而异,部分应用(如 Windsurf)要求硬编码令牌。
令牌安全最佳实践:最小化 scope(repo 仓库操作、read:packages 镜像访问、read:org 组织团队访问);不同项目/环境使用不同 PAT;定期轮换;绝不提交到版本控制;限制含令牌配置文件的文件权限(如 chmod 600 ~/.your-app/config.json)。
本地接入 GHES / ghe.com
标志 --gh-host 与环境变量 GITHUB_HOST 用于指定 GitHub Enterprise Server 或 ghe.com 的主机名:
- GHES 必须给主机名前缀
https://(否则默认http://,GHES 不支持); - ghe.com 使用
https://YOURSUBDOMAIN.ghe.com作为主机名。
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"-e",
"GITHUB_HOST",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
"GITHUB_HOST": "https://<your GHES or ghe.com domain name>"
}
}
安装到 VS Code 及其他 MCP 宿主
在 IDE 的 MCP 设置中加入如下 JSON(包含 inputs 密码提示,令牌不落盘到明文配置):
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "github_token",
"description": "GitHub Personal Access Token",
"password": true
}
],
"servers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
}
}
}
}
}
也可以把去掉 mcp 外层键的等价配置放入工作区 .vscode/mcp.json,以便与其他支持相同格式的主机应用共享。其他宿主的指南索引见 docs/installation-guides/。任何支持本地 MCP 服务器的宿主理论上都可接入本地 GitHub MCP Server,但具体配置语法以宿主文档为准。
从源码构建
没有 Docker 时可用 go build 在 cmd/github-mcp-server/ 目录构建二进制(用 -o 指定输出位置),然后以 github-mcp-server stdio 子命令运行,并确保设置了 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量:
{
"mcp": {
"servers": {
"github": {
"command": "/path/to/github-mcp-server",
"args": ["stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}
}
从源码结构看,stdio 子命令会先校验令牌(未设置即报错 GITHUB_PERSONAL_ACCESS_TOKEN not set),再通过 viper 统一读取命令行参数与环境变量组装配置,最后调用 ghmcp.RunStdioServer 启动 JSON-RPC over stdio 服务;http 子命令则对应 HTTP 传输。全部全局标志的定义见 main.go。
CLI 调试工具
github-mcp-server 二进制附带调试子命令,例如按名称、描述、输入参数名搜索工具(--max-results 控制返回数量;彩色输出需要 TTY,Docker 中请用 docker run -t 或 -it):
docker run -it --rm ghcr.io/github/github-mcp-server tool-search "issue" --max-results 5
github-mcp-server tool-search "issue" --max-results 5
工具配置体系:Toolsets 与 Tools 的精细控制
通过 --toolsets 控制功能组
GitHub MCP Server 支持用 --toolsets 标志启用/禁用功能组,从而控制 AI 工具可访问的 GitHub API 能力范围。只启用需要的工具集有助于模型做工具选择并减小上下文体积。工具集不仅包含 Tools,相关 MCP Resources 与 Prompts 也一并按工具集启停。
两种指定方式:
github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security
GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server
当两者同时提供时,环境变量 GITHUB_TOOLSETS 优先于命令行参数。 未指定任何工具集时使用默认工具集。更多常见配方(最小化配置、只读模式、工具与工具集组合)见 docs/server-configuration.md。
通过 --tools 指定单个工具
--tools 允许按工具名做更细粒度控制,可单独使用,也可与工具集、动态工具集发现叠加(叠加关系是加法):
# 仅指定工具
github-mcp-server --tools get_file_contents,issue_read,create_pull_request
GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" ./github-mcp-server
# 与工具集组合(加法):注册 repos、issues 全部工具外加 get_gist
github-mcp-server --toolsets repos,issues --tools get_gist
# 与动态工具集组合(加法):注册 get_file_contents 加动态工具集
github-mcp-server --tools get_file_contents --dynamic-toolsets
重要约束(README 明确列出):
- 工具、工具集、动态工具集三者可同时使用;
- 只读模式优先:设置
--read-only后,即使--tools显式指定了写工具也会被跳过; - 工具名必须精确匹配(如
get_file_contents而非getFileContents),无效工具名会让服务器启动即失败; - 工具重命名后,旧名称保留为别名以兼容旧配置,别名清单见 docs/deprecated-tool-aliases.md。
这些约束在源码中可以直接印证:pkg/inventory/builder.go 的 Build() 会对 WithTools() 指定的名称做清洗、别名解析,遇到无法识别的名称直接返回 unrecognized tools: ... 错误——即“启动即失败”的 fail fast 行为;pkg/inventory/filters.go 的 isToolEnabled 按固定顺序执行过滤链:工具自身 Enabled 函数 → 特性标志 → 只读过滤 → 构建器附加过滤器 → additionalTools 白名单(绕过工具集过滤)→ 工具集过滤。这解释了为什么“只读优先”以及 --tools 的加法语义。
Docker 下的工具集与工具配置
Docker 场景通过环境变量传递(GITHUB_TOOLSETS / GITHUB_TOOLS):
# 指定工具集
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" \
ghcr.io/github/github-mcp-server
# 仅工具
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" \
ghcr.io/github/github-mcp-server
# 工具与工具集组合(加法)
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_TOOLSETS="repos,issues" \
-e GITHUB_TOOLS="get_gist" \
ghcr.io/github/github-mcp-server
环境变量到标志的映射并非手写的:从源码看,main.go 中 viper.SetEnvPrefix("github") 与 SetEnvKeyReplacer(strings.NewReplacer("-", "_")) 将 toolsets 标志映射为 GITHUB_TOOLSETS、dynamic-toolsets 映射为 GITHUB_DYNAMIC_TOOLSETS、read-only 映射为 GITHUB_READ_ONLY,这就是各 GITHUB_* 环境变量生效的机制,也是“环境变量覆盖命令行参数”的底层原因。
特殊工具集:all 与 default
all:启用所有可用工具集,忽略其他配置:
./github-mcp-server --toolsets all
GITHUB_TOOLSETS="all" ./github-mcp-server
default:不指定任何工具集时实际使用的配置,当前包含 context、repos、issues、pull_requests、users 五组。在保留默认值的同时追加:
GITHUB_TOOLSETS="default,stargazers" ./github-mcp-server
这一默认清单与源码完全一致:pkg/github/tools.go 中 context、repos、issues、pull_requests、users 五个工具集元数据标记了 Default: true,而 pkg/inventory/builder.go 的 processToolsets 负责解析 all(命中即启用全部,返回 nil 表示无过滤)、展开 default 关键字、去空白、去重并跟踪未识别的工具集 ID。
可用工具集总表
| 工具集 | 说明 |
|---|---|
context |
强烈推荐:提供当前用户与所操作 GitHub 上下文的工具 |
actions |
GitHub Actions 工作流与 CI/CD 操作 |
code_security |
代码安全相关工具,如 GitHub Code Scanning |
dependabot |
Dependabot 工具 |
discussions |
GitHub Discussions 相关工具 |
gists |
GitHub Gist 相关工具 |
git |
GitHub Git API 低级别 Git 操作 |
issues |
GitHub Issues 相关工具 |
labels |
GitHub Labels 相关工具 |
notifications |
GitHub Notifications 相关工具 |
orgs |
GitHub Organization 相关工具 |
projects |
GitHub Projects 相关工具 |
pull_requests |
GitHub Pull Request 相关工具 |
repos |
GitHub Repository 相关工具 |
secret_protection |
秘密保护相关工具,如 GitHub Secret Scanning |
security_advisories |
安全公告相关工具 |
stargazers |
GitHub Stargazers 相关工具 |
users |
GitHub User 相关工具 |
仅远端服务器额外提供的工具集:
| 工具集 | 说明 |
|---|---|
copilot |
Copilot 相关工具(如 Copilot Coding Agent) |
copilot_spaces |
Copilot Spaces 相关工具 |
github_support_docs_search |
搜索官方文档以回答 GitHub 产品与支持问题 |
本地服务器还有 dynamic 元工具集(见下文动态工具发现),见 tools.go。
工具目录:按工具集全量梳理
以下工具清单继承自 README 的自动化工具表(START/END AUTOMATED TOOLS 区段),OAuth scope 为调用该工具所需(或可接受)的授权。
Actions(工具集 actions)
- actions_get(scope:
repo):获取 Actions 资源(工作流、运行、作业、制品)详情。必选method、owner、repo、resource_id;resource_id的含义随 method 变化:get_workflow传工作流 ID 或文件名(如ci.yaml),get_workflow_run/get_workflow_run_usage/get_workflow_run_logs_url传运行 ID,download_workflow_run_artifact传制品 ID,get_workflow_job传作业 ID。 - actions_list(scope:
repo):列出 Actions 资源。必选method、owner、repo;可选page(默认 1)、per_page(默认 30,最大 100)、resource_id(list_workflows不需要;list_workflow_runs可省略以列出全部运行;list_workflow_jobs、list_workflow_run_artifacts需运行 ID)、workflow_jobs_filter/workflow_runs_filter对象过滤。 - actions_run_trigger(scope:
repo):触发/管理 Actions 工作流。必选method、owner、repo;run_workflow需workflow_id(数字 ID 或main.yml、ci.yaml文件名)与ref(分支或标签),可选inputs;其他 method 需run_id。 - get_job_logs(scope:
repo):获取作业日志。必选owner、repo;job_id取单作业日志,failed_only=true时配合run_id取该运行中全部失败作业日志;可选return_content(返回日志内容而非 URL)、tail_lines。
Code Security(code_security,scope: security_events,接受 repo、security_events)
- get_code_scanning_alert:按
alertNumber、owner、repo获取单条代码扫描告警。 - list_code_scanning_alerts:列出告警,可选
ref(Git 引用)、severity、state(默认 open)、tool_name过滤。
Context(context)
- get_me:获取当前用户资料,无参数。
- get_team_members(scope:
read:org):按org、team_slug获取团队成员。 - get_teams(scope:
read:org):列出用户所属团队,user省略时为认证用户。
Dependabot(dependabot,scope: security_events,接受 repo、security_events)
- get_dependabot_alert:按
alertNumber、owner、repo获取单条告警。 - list_dependabot_alerts:列出告警,可选
severity、state(默认 open)。
Discussions(discussions,scope: repo)
- get_discussion / get_discussion_comments:获取讨论及评论(评论支持
after游标与perPage1–100 分页)。 - list_discussion_categories:列出讨论分类;
repo省略时查询组织级分类。 - list_discussions:列出讨论,支持
after游标、category分类 ID、orderBy+direction排序、perPage分页。
Gists(gists)
- create_gist(scope:
gist):content、filename必选,description、public可选。 - get_gist:按
gist_id获取内容。 - list_gists:可选
username(省略为认证用户)、since(ISO 8601)、分页。 - update_gist(scope:
gist):更新文件内容或描述。
Git(git,scope: repo)
- get_repository_tree:获取仓库树。必选
owner、repo;可选tree_sha(SHA 或分支/标签,默认默认分支)、recursive(默认 false)、path_filter(如src/前缀过滤)。
Issues(issues,scope 多为 repo)
- add_issue_comment:必选
body、issue_number、owner、repo。 - assign_copilot_to_issue:将 Copilot 指派给 Issue,可选
base_ref、custom_instructions。 - get_label:按
name获取标签(与 Labels 工具集共用)。 - issue_read:
method支持get(详情)、get_comments、get_sub_issues、get_labels;必选issue_number、owner、repo,支持page/perPage。 - issue_write:
method为create/update;可选title、body、assignees、labels、milestone、state、state_reason、duplicate_of、type(仅当仓库配置了 Issue 类型时使用,可先用list_issue_types查询合法值)。 - list_issue_types(scope:
read:org):按owner(组织)列出可用 Issue 类型。 - list_issues:支持
labels、state(缺省返回 open + closed)、since(ISO 8601)、orderBy+direction、游标分页。 - search_issues:
query使用 GitHub Issue 搜索语法;owner+repo同时提供时限定单仓库;支持sort(默认最佳匹配)、order。 - sub_issue_write:子 Issue 的
add/remove/reprioritize;重排时二选一after_id/before_id;add可加replace_parent替换父 Issue;注意sub_issue_id是 ID 而非编号。
Labels(labels,scope: repo)
- get_label / list_label:读取标签。
- label_write:
method为create/update/delete;color为不带#的 6 位十六进制(如f29513),create 必选、update 可选;update支持new_name重命名。
Notifications(notifications,scope: notifications)
- dismiss_notification:
threadID+state(read/done)。 - get_notification_details / list_notifications:列表支持
since/before(ISO 8601)、filter(default/participating/subscribed)、仓库级owner+repo过滤、分页。 - manage_notification_subscription / manage_repository_notification_subscription:
action为ignore/watch/delete。 - mark_all_notifications_read:可选
lastReadAt(默认当前时间)、仓库级过滤。
Organizations(orgs,scope: read:org)
- search_orgs:
query如microsoft、location:california、created:>=2025-01-01,自动限定type:org;支持sort、order、分页。
Projects(projects,scope: 读操作 read:project 接受 project,写操作 project)
- projects_get:
method指定获取项目/字段/条目详情;get_project_item需item_id,fields指定要包含的字段 ID(省略仅返回标题)。 - projects_list:
list_projects支持query(如roadmap is:open);list_project_items需project_number,强烈建议提供fields,否则只返回标题;分页per_page最大 50。 - projects_write:新增条目需
item_type(issue/pull_request)+issue_number或pull_request_number+item_owner/item_repo;update_project_item用updated_field对象(如{"id": 123456, "value": "New Value"},置null清空);delete_project_item需item_id。
Pull Requests(pull_requests,scope: repo)
- add_comment_to_pending_review:向最新待决评审追加行级评论,必选
body、path、pullNumber、subjectType、owner、repo;多行范围用startLine/line+startSide/side(LEFT 旧状态 / RIGHT 新状态)。 - add_reply_to_pull_request_comment:按
commentId回复。 - create_pull_request:必选
title、head、base、owner、repo;可选body、draft、maintainer_can_modify。 - list_pull_requests:支持
state、head、base、sort、direction、分页。 - merge_pull_request:可选
merge_method、commit_title、commit_message。 - pull_request_read:
method支持get、get_diff、get_status(head 提交的构建与检查状态)、get_files、get_review_comments(评审线程,含isResolved/isOutdated/isCollapsed元数据,用perPage/after游标分页)、get_reviews、get_comments。 - pull_request_review_write:对评审执行创建/提交/删除(
method必选)。 - request_copilot_review:请求 Copilot 评审,仅需
owner、pullNumber、repo。 - search_pull_requests:
query使用 PR 搜索语法,其余同search_issues。 - update_pull_request:更新
title、body、base、draft、state、maintainer_can_modify、reviewers。 - update_pull_request_branch:可选
expectedHeadSha做乐观并发控制。
Repositories(repos,scope: repo)
- create_branch:
branch必选,from_branch默认仓库默认分支。 - create_or_update_file:
branch、content、message、path必选;更新已有文件时提供sha(被替换文件的 blob SHA)。 - create_repository:
name必选;organization省略则建在个人名下;可选private、autoInit、description。 - delete_file / fork_repository:删除文件需分支与提交信息;fork 可选目标
organization。 - get_commit:
sha可为提交、分支或标签;include_diff默认 true。 - get_file_contents:
ref支持refs/tags/{tag}、refs/heads/{branch}、refs/pull/{pr_number}/head;sha优先于ref。 - get_latest_release / get_release_by_tag(
tag如v1.0.0)/ get_tag。 - list_branches / list_commits(可按
author、sha过滤)/ list_releases / list_tags:均支持page、perPage分页。 - push_files:一次提交推送多个文件,
files为{path, content}对象数组。 - search_code:
query使用 GitHub 代码搜索语法(如content:Skill language:Java org:github、NOT is:archived language:Python OR language:go、repo:github/github-mcp-server),支持精确匹配、语言与路径过滤;sort仅indexed。 - search_repositories:
query如machine learning in:name stars:>1000 language:python、topic:react、user:facebook;minimal_output默认 true(false 时返回完整 API 对象)。
Secret Protection(secret_protection,scope: security_events,接受 repo、security_events)
- get_secret_scanning_alert:按
alertNumber获取。 - list_secret_scanning_alerts:可选
state、resolution、secret_type(逗号分隔;默认返回全部默认模式,返回泛化模式需传自定义模式名)。
Security Advisories(security_advisories,scope: security_events)
- get_global_security_advisory:按
ghsaId(格式GHSA-xxxx-xxxx-xxxx)获取。 - list_global_security_advisories:过滤维度丰富——
affects(包@版本)、cveId、cwes、ecosystem、severity、type、isWithdrawn、published/modified/updated(ISO 8601 日期或区间)。 - list_org_repository_security_advisories(按
org)/ list_repository_security_advisories(按owner+repo):支持state、sort、direction。
Stargazers(stargazers,scope: repo)
- list_starred_repositories:
username默认认证用户;sort为created(收藏时间)或updated(最后推送时间)。 - star_repository / unstar_repository:必选
owner、repo。
Users(users,scope: repo)
- search_users:
query如john smith、location:seattle、followers:>100,自动限定type:user;sort按粉丝数、仓库数或加入时间。
远端服务器额外工具
- create_pull_request_with_copilot(
copilot工具集):用 Copilot Coding Agent 执行任务并创建 PR;owner、repo、problem_statement(任务详细描述)、title必选,base_ref可选。 - get_copilot_space / list_copilot_spaces(
copilot_spaces工具集):获取/列出 Copilot Space。 - github_support_docs_search(
github_support_docs_search工具集):检索官方文档回答产品与支持问题;query应原样传入用户最新消息,不做改写。
动态工具发现(Beta)
动态工具发现当前处于 beta 阶段,不适用于远端服务器。开启后,服务器不再一次性暴露全部工具,而是注册 enable_toolset、list_available_toolsets、get_toolset_tools 三个元工具,由 MCP 宿主根据用户提示按需列出并启用工具集,避免模型被过多工具干扰。
./github-mcp-server --dynamic-toolsets
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_DYNAMIC_TOOLSETS=1 \
ghcr.io/github/github-mcp-server
从源码看,动态模式下服务器会主动移除 all 与 default 两个元工具集(见 pkg/github/server.go 附近逻辑及 server_test.go 的对应断言),而 filters.go 中的 EnableToolset 方法在运行时把指定工具集标记为启用——这正是 enable_toolset 元工具背后的实现。
只读模式与 Lockdown 模式
只读模式
--read-only 只暴露只读工具,阻止对仓库、Issue、PR 的一切修改:
./github-mcp-server --read-only
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_READ_ONLY=1 \
ghcr.io/github/github-mcp-server
源码中该过滤发生在工具级判定链的第 3 步(r.readOnly && !tool.IsReadOnly() 即排除),且在动态工具集场景下同样生效(ToolsForToolset 也检查只读),这与 README“写工具即使显式指定也会被跳过”的描述一致。
Lockdown 模式
Lockdown 模式限制服务器从公共仓库呈现的内容:启用后,服务器会检查每条内容的作者是否具有该仓库的 push 权限。私有仓库不受影响,协作者对自己内容的访问也保持完整。
./github-mcp-server --lockdown-mode
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_LOCKDOWN_MODE=1 \
ghcr.io/github/github-mcp-server
按工具区分行为:作者缺乏 push 权限时直接返回错误的工具为 issue_read:get、pull_request_read:get;过滤掉无 push 权限用户内容的工具为 issue_read:get_comments、issue_read:get_sub_issues、pull_request_read:get_comments、pull_request_read:get_review_comments、pull_request_read:get_reviews。
i18n:覆盖工具描述
工具描述可通过在二进制同目录下放置 github-mcp-server-config.json 覆盖,键为工具名常量、值为新描述:
{
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
"TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
}
用 --export-translations 可导出当前译文,且会保留已有覆盖、补齐二进制新增的翻译项:
./github-mcp-server --export-translations
cat github-mcp-server-config.json
也支持环境变量覆盖:变量名与 JSON 键相同,加 GITHUB_MCP_ 前缀并全大写:
export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"
更多启动参数、镜像与安全说明
README 之外,从 main.go 的标志定义还可以确认一组实用参数:--log-file(日志路径)、--enable-command-logging(记录所有命令请求与响应)、--content-window-size(默认 5000)、--repo-access-cache-ttl(默认 5m,0s 禁用缓存)、--insiders(本地版 insiders 特性,对应 GITHUB_INSIDERS);HTTP 子命令另有 --port(默认 8082)、--base-url、--base-path、--scope-challenge(OAuth scope challenge 响应)。
镜像构建见 Dockerfile:Go 1.25 多阶段构建、CGO_ENABLED=0 静态链接、最终基于 distroless/base-debian12 最小运行时镜像,入口点为 /server/github-mcp-server,默认命令 http --port 5000——这说明该镜像面向远端/HTTP 托管场景;本地 stdio 场景通过 docker run -i 让宿主进程拉起二进制即可。
关于作为 Go 库的使用,README 明确声明:导出的 Go API 目前应视为不稳定,存在破坏性变更的可能。该模块采用 MIT 许可证,见 LICENSE。
总结
mcp_servers/github_official 提供了一条从“零配置接入 GitHub 上下文”到“按工具集/单工具精确授权”再到“只读 + Lockdown 双重内容治理”的完整能力阶梯:远端服务(OAuth/PAT)适合快速起步,Docker 与源码构建满足自托管与 GHES 需求;--toolsets/GITHUB_TOOLSETS、--tools/GITHUB_TOOLS、--read-only、--lockdown-mode、--dynamic-toolsets 共同构成细粒度控制面,且每一项行为都能在 pkg/inventory/ 与 pkg/github/tools.go 的源码中找到对应的过滤链、工具集元数据与元工具实现作为验证依据。