GitHub MCP Server For Codex

为Codex配置GitHub MCP服务器（macOS + Colima）

什么：此设置允许Codex通过安全的Docker桥接直接与GitHub通信，因此您可以使用自然语言搜索仓库、读取文件或打开问题。

🧠 TL;DR 快速入门

需要快速获取吗？复制/粘贴（替换为您的 macOS 用户名和 PAT）。

# 1. Install & start the Docker runtime
brew install colima && colima start

# 2. Pull the GitHub MCP Server image (pin a release when you need stability)
docker pull ghcr.io/github/github-mcp-server:latest
# docker pull ghcr.io/github/github-mcp-server:vX.Y.Z   # pin a specific release

# 3. Create ~/.github-mcp.env and confirm Docker can read the PAT
echo "GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_XXXXXXXXXXXXXXXXXXXXXXXX" > ~/.github-mcp.env
chmod 600 ~/.github-mcp.env
docker run --rm --env-file ~/.github-mcp.env alpine sh -lc 'test -n "$GITHUB_PERSONAL_ACCESS_TOKEN" && echo OK'

# 4. Add this block to ~/.codex/config.toml (update the username)
# 5. Launch Codex and approve the docker run when prompted
codex

# 6. Smoke test inside Codex
Using only the `github` MCP tools, call `get_me`.

[mcp_servers.github]
command = "docker"
args = [
  "run","-i","--rm","--pull=always",          # keep the image fresh (swap to :vX.Y.Z + drop --pull for pinned builds)
  "--name","github-mcp",
  "--env-file","/Users/YourMacUsername/.github-mcp.env",
  "ghcr.io/github/github-mcp-server:latest","stdio"
]

⚠️ 安全提示： ~/.github-mcp.env 持有有效令牌。请保持文件私密（chmod 600) 并且永远不要将其提交到 git。

______________________________________________________________________

🧱 安装先决条件

• 使用 Homebrew 的 macOS
• 科利马 （轻量级的Docker运行时）
• OpenAI Codex（命令行界面或VS Code扩展）
• 一个GitHub账户（个人或组织）

brew install colima
colima start           # launches the Docker daemon inside a VM
docker ps              # quick sanity check

Windows / Linux？ 在Windows上使用Docker Desktop（或WSL2 + Docker），在Linux上使用纯Docker引擎。Codex args 列表是相同的——只需更改 --env-file 路径以匹配您的平台（例如， C:\\Users\\you\\.github-mcp.env 在Windows上， /home/you/.github-mcp.env 在Linux上。

🔑 创建您的GitHub令牌

创建一个具有以下最低设置的个人访问令牌（新的细粒度类型）：

• 资源所有者：您的GitHub用户（例如， Xsamsx)
• 仓库访问权限：所有仓库，或选择您需要的仓库
• 仓库权限（根据需要调整）：

- 元数据：读取 - 内容：阅读（或如果你要推送更改，则为阅读&写入） - 问题：读取（或读取和写入） - 拉取请求：只读（或读写）

• 可选：添加操作、管理、提交状态等，以实现自动化

为任何强制使用SAML单点登录（SSO）的组织授权该令牌。GitHub会提供一个类似这样的值： github_pat_XXXXXXXXXXXXXXXX...。

范围快速参考

🔒 在本地存储令牌

在你的主目录中创建一个隐藏的环境文件，并设置权限锁定：

echo "GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_XXXXXXXXXXXXXXXXXXXXXXXX" > ~/.github-mcp.env
chmod 600 ~/.github-mcp.env

验证Docker能否读取令牌（如果未打印“OK”，请在打开Codex之前修复环境文件）：

docker run --rm --env-file ~/.github-mcp.env alpine sh -lc 'test -n "$GITHUB_PERSONAL_ACCESS_TOKEN" && echo OK'

可选的护栏功能，确保令牌永远不会出现在 Git 历史记录中：

echo ".github-mcp.env" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

可选：通过 GitHub CLI 进行最简单的身份验证（跳过环境文件）

已使用（某方式）登录 gh你可以通过官方的MCP扩展来运行服务器——无需PAT文件：

gh extension install shuymn/gh-mcp
gh mcp run    # starts github-mcp-server in Docker using your gh auth

Codex 看到的是同一个 MCP 端点；只需将您的配置指向相应的命令即可 gh mcp run 打印（或者通过将扩展命令连接到线路中，让Codex手动启动它） [mcp_servers.github]）。

⚙️ 配置Codex

编辑 ~/.codex/config.toml 并将快速启动中的代码块粘贴过来（更新用户名）。 --pull=always 保持容器更新；当你将某个标签（如）固定时 ghcr.io/github/github-mcp-server:vX.Y.Z，移除 --pull=always 用于可重复构建。

精简的工具集（保持上下文简洁）

服务器提供了多个工具集。对其进行精简，以优化Codex的工具选择并减少上下文干扰：

args = [
  "run","-i","--rm","--pull=always",
  "--name","github-mcp",
  "--env-file","/Users/YourMacUsername/.github-mcp.env",
  "ghcr.io/github/github-mcp-server:latest",
  "--toolsets","repositories,issues","stdio"
]

当直接运行二进制文件时，标志是相同的：

github-mcp-server --toolsets=issues,contents stdio

检查 github-mcp-server --help 对于当前的工具集列表（repositories， issues， pull_requests， workflows等）。

GitHub Enterprise（GHES 或自定义主机）

通过以下方式添加您的主机名 GITHUB_HOST：

args = [
  "run","-i","--rm","--pull=always",
  "--name","github-mcp",
  "--env-file","/Users/YourMacUsername/.github-mcp.env",
  "-e","GITHUB_HOST=https://your-org.ghe.com",
  "ghcr.io/github/github-mcp-server:latest","stdio"
]

🚀 发布与验证

colima start        # ensure Docker is running
codex               # launch Codex; approve the docker run when prompted
docker ps | grep github-mcp   # should list one running container

在Codex中，打开MCP视图（或运行 /mcp）并确认 github 已被列出。

提示包（复制 & 粘贴）

使用以下任意提示来证明服务器正常工作——每个提示都仅限于GitHub MCP工具的范围内。

• 列出我的仓库（表格形式）：

  Using only the github MCP tools, call get_me. Then call search_repositories with q="user:{login}" and per_page=100. Return a table with columns: full_name | visibility | description. If over 100, paginate and combine.

• 打开一个仓库并预览README文件：

  With the github MCP tools, get the default branch of /, then fetch README.md via get_file_contents. Show the first 30 lines with line numbers.

• 查找我最近7天创建的问题：

  Using only github MCP tools, query issues with q="author:{login} is:issue created:>=7d"; return repository | number | title | state | created_at.

• 创建一个测试问题（需要写入权限范围）：

  Using github MCP tools, create an issue in / titled "MCP test" with body "hello from Codex." Return the issue URL.

• 在我的组织中搜索包含某个字符串的代码：

  With github MCP, run a code search q="org:  in:file"; list repo | path | html_url for the first 50 matches.

🔄 第二天 操作与诊断

• 启动/停止程序：

- 启动 Docker： colima start - 发射编码： codex - 与……一起离开 Ctrl+C (避免 Ctrl+Z); 容器因（某种原因）而消失 --rm - 手动停止： docker stop github-mcp - 清理散落的集装箱：

    docker ps -q --filter ancestor=ghcr.io/github/github-mcp-server | xargs -r docker stop

• 定期刷新图像： docker pull ghcr.io/github/github-mcp-server:latest （或者将你置顶的标签推上去）。
• 按计划轮换PAT（可能指某种设备或系统，如“个人防护装备”Personal Apparatus或“专利申请跟踪”等，具体需根据上下文确定）——替换其中的值 ~/.github-mcp.env 并重启Codex。
• 日志和错误：检查 ~/.codex/logs/latest.log 如果Codex无法启动服务器，您可以通过调整超时设置来解决 startup_timeout_sec 或者 tool_timeout_sec 在……之下 [mcp_servers.github] 如果大请求超时。

🛠️ 故障排除

• 401 凭证无效\

~/.github-mcp.env 令牌缺失或已过期。请重新运行完整性检查命令，并在需要时生成一个新的PAT（个人访问令牌）。

• 未找到任何仓库\

PAT（个人访问令牌）缺少仓库访问权限。请编辑令牌并添加元数据/内容范围以及特定的仓库或“所有仓库”。

• 组织仓库缺失\

授予组织范围（read:org 或者其细粒度等价物，并批准使用SAML单点登录（SSO）来获取该令牌。

• Docker 命令被拒绝unrecognized flag）\

更新图像（docker pull ...) 以匹配你正在使用的标志，或者移除可选标志，如 --toolsets。

• 《法典》从未列出 /mcp/github\

跑 /mcp 刷新；如果仍然缺失，请检查 ~/.codex/logs/latest.log 检查 Docker 的标准错误输出，并确认 Colima 正在运行。

高级：用于快速curl的HTTP模式

更喜欢使用HTTP而非stdio？您可以以HTTP模式运行服务器进行轻量级调试：

docker run --rm -p 3000:3000 --env-file ~/.github-mcp.env ghcr.io/github/github-mcp-server:latest http --listen 0.0.0.0:3000
curl -s http://localhost:3000/tools/list | jq

根据需要交换端口或标志——参见 github-mcp-server http --help 以获取全部选项。Codex 仍然期望使用标准输入输出（stdio），因此保留 HTTP 用于手动测试。

🛡️ 安全注意事项

• PAT（专利申请技术或某种特定技术，具体含义需根据上下文确定）仅保留在磁盘上 ~/.github-mcp.env。
• 文件权限 600 阻止其他用户登录该机器。
• 如果遵循全局忽略提示，该令牌绝不会出现在Docker镜像、Codex配置或git历史记录中。
• 定期旋转PAT（个人访问令牌）并更新env文件。
• 如果你采用GitHub CLI扩展，令牌将保留在你的（系统/环境中） gh 使用钥匙串而不是环境文件。

🪛 无Docker回退方案（从源代码构建）

没有 Docker？直接使用 Go 1.21+ 构建服务器：

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
go build ./cmd/github-mcp-server
./github-mcp-server stdio

对生成的二进制文件进行点检（例如， /Users/you/github-mcp-server/github-mcp-server) 而不是 docker。

📝 附录

• 显示隐藏文件（点文件）： ls -la ~
• 编辑env文件： nano ~/.github-mcp.env
• 确认令牌，使用REST API（需要 jq):

  curl -s -H "Authorization: Bearer $(cut -d= -f2 ~/.github-mcp.env)" https://api.github.com/user | jq .login

欢迎提交PR（Pull Request）以改进GHES（GitHub Enterprise Server）、设置多组织环境、分享额外的自动化技巧或提出新的提示想法。