Klavis 中的 github_official:GitHub 官方 MCP Server 部署、工具集配置与安全模式实战指南

原创2026-09-16 16:30:151,947 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端本地部署认证鉴权API网关

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 配置

前置条件:

  1. 支持远端服务器的 MCP 宿主(VS Code 1.101+、Claude Desktop、Cursor、Windsurf 等);
  2. 已启用适用的平台策略(见 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 宿主的安装指南(相对仓库根目录):

注意:每个 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 与源码构建

前置条件

  1. 安装 Docker(此处仅为概念依赖,实际操作以本机已装 Docker 为准);
  2. Docker 处于运行状态。镜像地址为 ghcr.io/github/github-mcp-server,是公开镜像;拉取报错时可能是过期令牌导致,可执行 docker logout ghcr.io 后重试;
  3. 创建 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 游标与 perPage 1–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 的源码中找到对应的过滤链、工具集元数据与元工具实现作为验证依据。

登录后查看全文
klavis