企业官网建设流程全解析

GitHub MCP Server 怎么启用 read-only 与 lockdown 模式限制写操作？

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

如果你在用 GitHub MCP Server 时不想让 AI 客户端随意改动 issue、PR 或仓库，就需要启用read-only 模式；如果你还担心公共仓库里陌生人发的 issue/PR 内容被模型读取（提示注入风险），可以再加lockdown 模式。两个开关相互独立、可以叠加：read-only 决定"哪些工具可用"，lockdown 决定"公共仓库里哪些内容会展示"。本文给出本地（stdio）与远程（HTTP）两种部署方式下的完整配置、验证方式和适用边界。

先明确两个模式各自的作用，避免把 lockdown 误当成写操作限制：

• read-only 模式：禁用所有非只读工具。即使你显式要求了某个写工具（如create_issue），它也不会出现。read-only 是严格的安全过滤，优先于其他任何工具配置（见 docs/server-configuration.md）。
• lockdown 模式：只作用于公共仓库的内容过滤。启用后，服务器会检查每条内容的作者是否对该仓库有 push 权限：私有仓库不受影响，协作者对自己内容的访问完全保留。文档明确说明它不是授权边界：它不改变底层凭证能读或写什么，被过滤掉的内容仍可能通过其他工具或直接用同一凭证访问 GitHub API 获得。

本地服务器（stdio / Docker）启用

本地服务器下，两种模式都支持命令行 flag 和环境变量两种写法（配置项对照见 docs/server-configuration.md 的 Quick Reference 表）：

1. 从源码构建的二进制

README 中的用法（<your-token>换成你自己的 GitHub Personal Access Token）：

# 只启用 read-only ./github-mcp-server --read-only # 只启用 lockdown ./github-mcp-server --lockdown-mode # 两者叠加：flag 可以任意组合 ./github-mcp-server --read-only --lockdown-mode

也可以用环境变量代替 flag，例如GITHUB_READ_ONLY=1、GITHUB_LOCKDOWN_MODE=1。

如果从源码直接运行（需要 Go 环境），服务器配置指南中的启动方式是go run ./cmd/github-mcp-server stdio ...，flag 加在stdio子命令之后：

go run ./cmd/github-mcp-server stdio --read-only --lockdown-mode

2. Docker 部署

README 给出的 Docker 写法，通过环境变量开启，两个模式可各加一条-e：

# read-only docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \ -e GITHUB_READ_ONLY=1 \ ghcr.io/github/github-mcp-server # lockdown docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \ -e GITHUB_LOCKDOWN_MODE=1 \ ghcr.io/github/github-mcp-server

同样可以两条环境变量同时传入，实现叠加。

远程服务器（HTTP）启用

远程服务器（https://api.githubcopilot.com/mcp/）的配置项对照表见 docs/remote-server.md：

read-only：header 或 URL 路径二选一

Header 方式（示例格式与 docs/server-configuration.md 中的 VS Code 配置一致）：

{ "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "X-MCP-Toolsets": "issues,repos,pull_requests", "X-MCP-Readonly": "true" } }

URL 路径方式，任何工具集 URL 末尾追加/readonly即可，例如默认工具集或指定工具集：

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

注意：路径中的{toolset}只能写单个工具集，不能逗号分隔多个；要组合多个工具集请用X-MCP-Toolsetsheader（docs/remote-server.md 的 URL Path Parameters 一节）。

lockdown：header，以及它的"上限"语义

{ "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "X-MCP-Lockdown": "true" } }

远程 header 的取值规则：X-MCP-Readonly和X-MCP-Lockdown在值为空、false、f、no、n、0、off（忽略大小写和首尾空白）时解析为 false，其余任何值都解析为 true。

有一个容易踩坑的语义：在 HTTP 模式下，服务端已启用的 lockdown（运营方通过--lockdown-mode/GITHUB_LOCKDOWN_MODE开启）是一个上限——X-MCP-Lockdownheader 可以在运营方未全局开启时为单个请求启用 lockdown，但不能把运营方已启用的 lockdown 关掉，也永远无法放宽到低于运营方的配置。

两种模式的远程配置可以写在同一个headers块里，docs/remote-server.md 的组合示例（这里把 lockdown 也置为 true）：

{ "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "X-MCP-Toolsets": "repos,issues", "X-MCP-Readonly": "true", "X-MCP-Lockdown": "true" } }

验证配置是否生效

验证 read-only：列出工具，确认写工具已消失

仓库自带的 mcpcurl 工具会连接 stdio 服务器、拉取工具 schema 并把每个工具生成为 CLI 子命令，适合核对工具清单（构建它需要 Go 1.24 及以上）：

cd cmd/mcpcurl go build -o mcpcurl

然后让它连接一个开启了 read-only 的本地服务器并列出工具：

./mcpcurl --stdio-server-cmd "go run ./cmd/github-mcp-server stdio --read-only" tools --help

判断标准：tools --help输出的工具列表里应该只有只读工具，create_issue、add_issue_comment、update_issue这类写工具不再出现（mcpcurl 文档中的示例输出展示了未过滤服务器上create_issue等写工具在列）。docs/server-configuration.md 还给了一个反向佐证：issues工具集虽然包含create_issue，但在 read-only 模式下它会被排除。

验证 lockdown：按工具区分"报错"与"过滤"两种行为

README 明确列出了 lockdown 模式下各工具的具体行为。以下两个列表是文档原样记录，验证时对照即可：

作者无 push 权限时直接返回错误的工具：

• issue_read:get
• pull_request_read:get
• pull_request_read:get_diff
• pull_request_read:get_files
• pull_request_read:get_commits

静默过滤掉无 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

一个有区分度的测试对象是机器人账号：github-actions[bot]和copilot是文档明确列出的可信 bot，其内容（如 CI 生成的 commit、评论）不受 lockdown 过滤，无论是否有 push 权限。

配置冲突排查

docs/server-configuration.md 的 Troubleshooting 表给出了相关条目：

另外记住优先级规则（docs/server-configuration.md）：read-only 优先于其他一切工具配置；--exclude-tools/X-MCP-Exclude-Tools优先于工具集和单个工具——列出的工具无论如何都会被排除。

边界与限制

• lockdown 不是安全边界：它是降低提示注入风险的 best-effort 内容过滤，不限制底层凭证本可读取或写入的内容；被某个工具过滤掉的内容，可能仍能通过同一凭证的其他工具或直接 GitHub API 访问得到（README、docs/server-configuration.md 均有相同表述）。
• read-only 只影响工具暴露：它让服务器不再提供写工具，凭证本身的权限范围不变。
• 私有仓库不受 lockdown 影响，协作者对自己内容的访问也完全保留。
• 不指定任何配置时，服务器使用默认工具集：context、issues、pull_requests、repos、users（docs/server-configuration.md）。

配置完成并验证工具列表后，如需进一步收窄范围，可以继续阅读 docs/server-configuration.md 中--toolsets/--tools/--exclude-tools的组合用法，与两个模式任意叠加。

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