GitHub MCP Server 怎么配置 toolsets 与单个 tools 来控制可用工具范围？-编程实验室

GitHub MCP Server 怎么配置 toolsets 与单个 tools 来控制可用工具范围？

【免费下载链接】github-mcp-serverGitHub's official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server

如果你的 MCP 客户端里 GitHub MCP Server 暴露的工具太多，影响模型选工具或占用上下文，就可以用toolsets（工具集）和tools（单个工具）两级控制把可用范围收敛到需要的部分。本地服务通过--toolsets/--tools命令行参数或GITHUB_TOOLSETS/GITHUB_TOOLS环境变量配置；远程托管服务（https://api.githubcopilot.com/mcp/）通过X-MCP-Toolsets/X-MCP-Tools请求头或/x/{toolset}URL 路径配置。两者概念一致，下文分开给出各自的完整写法。

配置前先知道这几条规则

默认行为：不指定任何 toolset 时，服务器使用默认 toolsets：context、issues、pull_requests、repos、users。
组合是增量的（additive）：tools和toolsets可以同时使用，工具集里已有工具再加单个工具不会互相覆盖。例如--toolsets repos,issues --tools get_gist会注册repos和issues的全部工具，外加get_gist。
排除优先：--exclude-tools/X-MCP-Exclude-Tools列出的工具无论如何都不可用，即使其 toolset 已启用或该工具被显式加进--tools。
只读模式优先级最高：开启--read-only/X-MCP-Readonly后，写入类工具即使被显式请求也会被禁用（例如issues工具集里的create_issue在只读模式下不可用）。
名称必须精确：工具名必须完全匹配，例如get_file_contents而不是getFileContents。本地服务遇到无效工具名会在启动时报错退出。
toolset 不止包含 Tools：相应的 MCP Resources 和 Prompts 在适用时也会随 toolset 一起启用。
本地服务的优先级：GITHUB_TOOLSETS环境变量与--toolsets同时提供时，环境变量优先。

可用的 toolset 全表见 README 的 Available Toolsets 章节，常用的有context（强烈建议保留，提供当前用户与上下文信息）、repos、issues、pull_requests、actions、code_security、gists等；完整工具清单见 README 的 Tools 章节，配置时必须按那里列出的精确名称填写。

本地服务：用 toolsets 收窄范围

以 Docker 方式运行时，把 toolset 允许列表放进GITHUB_TOOLSETS环境变量（<your-token>替换为你自己的 GitHub PAT）：

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 时，直接给进程传参或设置环境变量：

github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security

GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server

两个特殊值：

all：启用全部可用 toolset，./github-mcp-server --toolsets all；
default：等价于默认的五个 toolset。想"保留默认再加一些"时写GITHUB_TOOLSETS="default,stargazers" ./github-mcp-server。

本地服务：只开单个工具，或与 toolsets 叠加

明确知道只需要哪几个工具时，用--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

toolset 加单个工具的典型写法——整组启用repos和issues，再从gists里只挑get_gist：

github-mcp-server --toolsets repos,issues --tools get_gist

Docker 下同样通过环境变量叠加：

# Tools only 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 # Tools combined with toolsets (additive) 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

想"开大工具集但砍掉个别危险工具"时，用排除参数：

github-mcp-server --toolsets pull_requests --exclude-tools=create_pull_request,merge_pull_request

结果：pull_requests工具集全部启用，但create_pull_request与merge_pull_request被移除，只剩读取和 review 类工具。

在 MCP 客户端配置文件中怎么写

VS Code 的 MCP 配置用 JSON 描述进程，args里带stdio子命令加参数即可（${input:github_token}是 VS Code 安装流程中的输入变量，由 VS Code 在配置时让你填入 token；其他 MCP 宿主则直接写自己的 token 环境变量，各宿主的配置语法参考安装指南）：

{ "type": "stdio", "command": "go", "args": [ "run", "./cmd/github-mcp-server", "stdio", "--toolsets=repos,issues", "--tools=get_gist,pull_request_read" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" } }

对应效果：仓库和 issue 相关工具全开，外加get_gist与pull_request_read。更多组合示例（最小配置、只读模式等）见服务器配置指南。

远程服务：用请求头或 URL 路径

远程服务没有启动参数，配置方式是给 HTTP 连接加请求头。同时启用 toolset 与单个工具：

{ "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "X-MCP-Toolsets": "repos,issues", "X-MCP-Tools": "get_gist,pull_request_read" } }

排除工具与只读模式同理，用X-MCP-Exclude-Tools、X-MCP-Readonly头。也可以只用 URL 路径选单个toolset，例如：

{ "type": "http", "url": "https://api.githubcopilot.com/mcp/x/issues/readonly" }

路径规则要注意：{toolset}只能写一个工具集，不支持逗号分隔列表，要组合多个 toolset 必须用X-MCP-Toolsets头；/x/all表示全部 toolset，URL 尾部可追加/readonly、/insiders等修饰。完整路径模式与请求头说明见远程服务文档。

结果验证与常见问题排查

配置正确与否可以从这几条文档明确的行为来判断：

本地服务：--tools里出现无效工具名时，服务器启动失败并给出错误信息。启动报错时先检查工具名拼写，对照 Tools 列表使用精确名称。
远程服务：X-MCP-Tools里的无效工具会抛错并阻止服务器启动；而X-MCP-Toolsets里的无效或未知 toolset 会被静默忽略，不报错也不阻止启动——如果远程端"看起来没生效"，优先怀疑 toolset 名拼错了。
工具缺失：官方排查表给出的对应关系是"Tools missing → Toolset not enabled → 添加所需 toolset 或具体工具"（见服务器配置指南的 Troubleshooting 一节）。
写入工具不生效：通常是只读模式开着，移除--read-only或X-MCP-Readonly头即可。
工具改名：工具重命名后旧名会保留为别名，旧配置不会直接报错，详见工具重命名说明。

两个容易踩的边界：

远程服务有本地没有的 toolset（copilot、copilot_spaces、github_support_docs_search，见 README），它们只在远程端可用；反过来本地图表里列的 toolset 在远程端都可用。
toolsets/tools 控制的是"暴露给模型哪些工具"，另外还有一层独立的、自动生效的 scope 过滤：经典 PAT（ghp_前缀）会在启动时按 token 权限过滤工具，这不需要配置，与本文的参数不冲突。

按上面的顺序操作即可：先确定用本地还是远程，选定要保留的 toolset 列表，必要时叠加单个工具或排除项，最后在 MCP 客户端重启服务器确认启动无报错、客户端里出现的工具列表与配置一致。

【免费下载链接】github-mcp-serverGitHub's official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考