← MCP

模型与开放条件Model & openness

它自己不调模型。 它是被客户端调用的接口实现 —— 选哪个模型是客户端的事。

它把 GitHub 平台能力包装成 MCP 工具：仓库、issue、PR、Actions、code scanning 等。

两个细节：

• 工具 schema 在协议版本 2026-07-28 及以后返回带类型的 structuredContent， 老客户端退回纯文本

• 工具描述可以用 github-mcp-server-config.json 或 GITHUB_MCP_* 环境变量覆写（便于本地化）

It calls no model itself. It is an interface implementation called by clients — which model to pick is the client's business.

It wraps GitHub platform capabilities as MCP tools: repositories, issues, PRs, Actions, code scanning, etc. Two details:

• Tool schemas return typed structuredContent on protocol version 2026-07-28 and later; older clients fall back to plain text

• Tool descriptions can be overridden via github-mcp-server-config.json or GITHUB_MCP_* environment variables (useful for localization)

运行位置Where it runs

两种运行形态：远程托管，或本地进程。

远程托管由 GitHub 自己运营，端点 https://api.githubcopilot.com/mcp/。

本地形态有三种跑法：

• Docker 镜像 ghcr.io/github/github-mcp-server
• go build 出来的二进制
• 自带 HTTP 模式 github-mcp-server http（默认端口 8082）

⚠ GitHub Enterprise Server 不支持远程托管（官方明写）。只能用本地形态。 ghe.com 可以走远程，但有独立端点。

官方对远程形态的说法：「the easiest method for getting up and running」 「no local setup or runtime required」

Two run forms: remotely hosted, or a local process.

Remote hosting is operated by GitHub itself, endpoint https://api.githubcopilot.com/mcp/.

The local form runs three ways:

• Docker image ghcr.io/github/github-mcp-server
• A go build binary
• Its built-in HTTP mode github-mcp-server http (default port 8082)

⚠ GitHub Enterprise Server does not support remote hosting (stated explicitly by the official docs). Only the local form works. ghe.com can use remote hosting, but on a separate endpoint.

The official wording on the remote form: "the easiest method for getting up and running" "no local setup or runtime required"

本地文件Local files

不碰你本机的文件系统。

它操作的是 GitHub 平台：远程仓库、issue、PR。它跟你本地的 git 仓库没有直接关系。 本地 git 操作见本站的 git 条目。

唯一贴近「文件」的能力，是操作远端仓库内容：

• get_file_contents —— 读文件或目录
• create_or_update_file / push_files —— 写文件
• delete_file —— 删文件

作用域是 GitHub 上的 repo / branch。容器形态下也不需要挂载本地仓库。

It never touches your local file system.

It operates on the GitHub platform: remote repositories, issues, PRs. It has no direct relation to your local git repositories. For local git operations see this site's git entry.

The only capability close to "files" is operating on remote repository content:

• get_file_contents — read a file or directory
• create_or_update_file / push_files — write files
• delete_file — delete a file

The scope is repos/branches on GitHub. The container form needs no local repository mount either.

关机后的任务Tasks after shutdown

远程托管形态与你的客户端进程无关。服务在 GitHub 那边，你关机它还在线。

本地形态随客户端生死 —— stdio 子进程退出就停。 自托管 HTTP 模式则是你自己运营的常驻服务。即 github-mcp-server http 加反向代理。

⚠ 它不提供「后台任务续跑」语义。 它的模式是有状态 HTTP / stdio 会话， 官方没有断点续跑机制。所谓「一直在」指的是远程托管形态的可用性， 而这个可用性取决于 GitHub 侧的服务状态。

The remotely hosted form is independent of your client process. The service lives on GitHub's side; it stays online when you shut down.

The local form lives and dies with the client — the stdio child process stops on exit. The self-hosted HTTP mode is a resident service you operate yourself, i.e. github-mcp-server http behind a reverse proxy.

⚠ It offers no "background task resumption" semantics. Its modes are stateful HTTP / stdio sessions; there is no official checkpoint-resume mechanism. "Always on" refers to the availability of the remotely hosted form — and that availability depends on GitHub's service status.

工具与扩展Tools & extensions

工具集（toolsets）是这条目的核心机制。

裁剪能力有四层手段：

• --toolsets / GITHUB_TOOLSETS（远程用 X-MCP-Toolsets 头，或 /x/{toolset} 路径）
• --tools / GITHUB_TOOLS —— 精确到单个工具
• --exclude-tools —— 排除工具
• 远程形态下每个 toolset 一个 URL，便于按场景组合

默认工具集是 5 组：context · repos · issues · pull_requests · users。

另有 20+ 组可开：actions · code_security · dependabot · discussions · gists · git · governance · labels · notifications · orgs · projects · secret_protection · security_advisories · stargazers · code_quality · copilot 等。

远程形态还有专属工具集，如 Copilot Spaces、GitHub Support Docs Search。

Toolsets are the core mechanism of this entry.

Narrowing capability has four layers of control:

• --toolsets / GITHUB_TOOLSETS (remote: the X-MCP-Toolsets header, or the /x/{toolset} path)
• --tools / GITHUB_TOOLS — down to the individual tool
• --exclude-tools — exclude tools
• In the remote form each toolset has its own URL, easy to combine per scenario

The default toolsets are 5 groups: context · repos · issues · pull_requests · users.

Another 20+ groups can be enabled: actions · code_security · dependabot · discussions · gists · git · governance · labels · notifications · orgs · projects · secret_protection · security_advisories · stargazers · code_quality · copilot, etc.

The remote form also has exclusive toolsets, e.g. Copilot Spaces and GitHub Support Docs Search.

上下文与记忆Context & memory

没有跨会话记忆。 每次会话独立。状态在 GitHub 平台本身（仓库、issue、PR 的持久状态）， 不在 server 里。

有一条官方特有的上下文控制。Insiders 模式下 list_* 工具可以返回 CSV （csv_output 特性标志），用来压缩列表类响应。

⚠ 那是响应格式优化，不是记忆机制。

官方对它的说法：「reduce response context for agents」

README 没有提供任何内建记忆或检索层。

No cross-session memory. Each session is independent. State lives on the GitHub platform itself (persistent state of repos, issues, PRs), not in the server.

One official-specific context control exists. In Insiders mode list_* tools can return CSV (the csv_output feature flag), used to compress list-type responses.

⚠ That is a response-format optimization, not a memory mechanism.

The official wording: "reduce response context for agents"

The README provides no built-in memory or retrieval layer.

权限与限制Permissions & limits

权限由 GitHub token 决定，官方另给三层收紧手段。

• ① read-only 模式 —— --read-only / GITHUB_READ_ONLY / X-MCP-Readonly
• ② lockdown 模式 —— --lockdown-mode / X-MCP-Lockdown
• ③ scope filtering —— 经典 PAT 在启动时按 token scope 隐藏无权限工具； OAuth 走按需 scope challenge

read-only 是强制过滤且优先级最高：即使你显式请求写工具，也会被禁用。

⚠ lockdown 不是授权边界。 官方明确它只是 best-effort 的内容过滤器 （过滤公开仓库里无 push 权限用户产出的内容），不改变凭据本身能读写什么。

写与删除能力是齐全的：create / update / delete file、push_files、 merge_pull_request、create_repository、delete_repository 等。

高危工具要按需授权（例如 delete_repo scope）。

官方称 read-only 是「strict security filter」

Permissions are determined by the GitHub token; the official docs add three narrowing controls.

• ① read-only mode — --read-only / GITHUB_READ_ONLY / X-MCP-Readonly
• ② lockdown mode — --lockdown-mode / X-MCP-Lockdown
• ③ scope filtering — classic PATs hide tools the token lacks at startup; OAuth uses on-demand scope challenges

read-only is an enforced filter with the highest precedence: even if you explicitly request write tools, they get disabled.

⚠ lockdown is not an authorization boundary. The official docs state it is only a best-effort content filter (filtering content produced by users without push access in public repositories); it does not change what the underlying credential can read or write.

Write and delete capabilities are complete: create / update / delete file, push_files, merge_pull_request, create_repository, delete_repository, etc. High-risk tools require on-demand authorization (e.g. the delete_repo scope).

The official docs call read-only a "strict security filter"

适合什么任务Best for

一句话：让任意 MCP 客户端用自然语言操作 GitHub。

客户端包括 VS Code、Claude Desktop、Cursor、Windsurf、Codex、Gemini CLI 等。

能做的事：读代码与仓库结构、管 issue 与 PR、监控 Actions。 还能查 code scanning / dependabot 安全告警、读通知。

远程托管形态适合「不想自己运维」的人。 本地 Docker 形态适合：GitHub Enterprise Server 用户 · 需要自托管 HTTP 的人 · 要离线可控的人。

不适合两类场景。一是需要操作本地文件系统，那是 filesystem / git server 的活。 二是需要跨会话记忆的场景。

In one sentence: it lets any MCP client operate GitHub in natural language.

Clients include VS Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini CLI, etc. What it can do: read code and repository structure, manage issues and PRs, monitor Actions. It can also check code scanning / dependabot security alerts and read notifications.

The remotely hosted form suits people who do not want to operate it themselves. The local Docker form suits: GitHub Enterprise Server users · people who need self-hosted HTTP · people who want offline control.

Not a fit for two kinds of scenarios. First, operating the local file system — that is the filesystem / git server's job. Second, scenarios needing cross-session memory.

传输方式Transport

两种形态：本地 stdio，或远程托管 HTTP。

本地形态走 stdio，两种跑法：Docker 镜像 ghcr.io/github/github-mcp-server，或 github-mcp-server stdio 二进制。

远程托管形态走 Streamable HTTP，端点是 https://api.githubcopilot.com/mcp/。

还能自托管 HTTP 模式（github-mcp-server http），支持 OAuth 元数据端点与 scope challenge。

远程形态可以加 URL 路径修饰：

• /readonly —— 只读
• /insiders —— 内部特性
• /x/{toolset} —— 只暴露某个 toolset
• 以上可以互相组合

⚠ 不同形态的权限边界不一样，必须分别配置。

核验：官方 README 与 remote-server.md（2026-10-08）

Two forms: local stdio, or remotely hosted HTTP.

The local form uses stdio, two ways to run: the Docker image ghcr.io/github/github-mcp-server, or the github-mcp-server stdio binary.

The remotely hosted form uses Streamable HTTP, endpoint https://api.githubcopilot.com/mcp/.

You can also self-host the HTTP mode (github-mcp-server http), with OAuth metadata endpoints and scope challenges.

The remote form accepts URL path modifiers:

• /readonly — read-only
• /insiders — insider features
• /x/{toolset} — expose only one toolset
• These can be combined

⚠ The permission boundary differs between forms and must be configured separately.

Verified against: the official README and remote-server.md (2026-10-08)

认证机制Authentication

本地 stdio 有三种认证方式。

• 浏览器 OAuth —— github.com 上官方镜像自带 app 凭据，token 只存内存
• PAT —— 环境变量 GITHUB_PERSONAL_ACCESS_TOKEN，优先级高于 OAuth
• GitHub App —— 给非交互式的 stdio 用

远程托管两种：OAuth（用 GitHub 凭据，缺 scope 时按需 scope challenge）， 或 PAT（请求头 Authorization: Bearer）。

⚠ 一个容易踩的坑：两类 PAT 的行为不同。

• 细粒度 PAT（github_pat_）不做 scope 过滤 —— 所有工具都显示， 权限由 API 侧强制

• 经典 PAT（ghp_） 才在启动时按 scope 隐藏工具

GitHub Enterprise Server / ghe.com 需要自带 OAuth App 或 GitHub App。

Local stdio has three authentication methods.

• Browser OAuth — on github.com the official mirror ships app credentials; the token is kept in memory only
• PAT — environment variable GITHUB_PERSONAL_ACCESS_TOKEN, takes precedence over OAuth
• GitHub App — for non-interactive stdio

Remote hosting has two: OAuth (using GitHub credentials, with on-demand scope challenges when a scope is missing), or a PAT (the Authorization: Bearer header).

⚠ An easy trap: the two PAT kinds behave differently.

• Fine-grained PATs (github_pat_) do no scope filtering — all tools are shown, permissions are enforced API-side

• Only classic PATs (ghp_) hide tools by scope at startup

GitHub Enterprise Server / ghe.com require your own OAuth App or GitHub App.

权限范围Permission scope

作用域就是 GitHub token 的权限范围 —— 能读，也能写和删。

可以收紧的有三层：read-only 模式强制只读（优先级最高）· toolsets 裁剪缩小暴露面 · lockdown 模式过滤不可信内容 （⚠ 官方强调它不是授权边界）。

写 / 删除能力是齐全的，例如：

• 文件：create_or_update_file / push_files / delete_file
• 仓库：create_repository / delete_repository（需 delete_repo）
• PR：create_pull_request / merge_pull_request
• 其它：label_write / projects_write / create_repository_ruleset

没有独立的审批机制。 delete_repository 会走多轮确认， 但那是交互式 elicitation，不是审批层 —— 别把它当审批用。

The scope is the permission range of the GitHub token — it can read, and also write and delete.

Three layers can narrow it: read-only mode enforces read-only (highest precedence) · toolsets trimming shrinks the exposed surface · lockdown mode filters untrusted content (⚠ the official docs stress it is not an authorization boundary).

Write / delete capabilities are complete, for example:

• Files: create_or_update_file / push_files / delete_file
• Repositories: create_repository / delete_repository (requires delete_repo)
• PRs: create_pull_request / merge_pull_request
• Others: label_write / projects_write / create_repository_ruleset

There is no independent approval mechanism. delete_repository goes through multi-round confirmation, but that is interactive elicitation, not an approval layer — do not treat it as one.

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.