在 OpenAI Codex 中安装与配置 GitHub MCP Server远程托管与本地 Docker 双方案实战【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server本篇指南讲解如何在 OpenAI CodexCLI 与 IDE 扩展中接入 GitHub MCP Server使 Codex 通过自然语言直接操作 GitHub 仓库、Issue、Pull Request、Actions 工作流与 Gist。文章完整覆盖远程托管服务器的零本地依赖接入方式PAT 认证、本地 Docker 自托管方式OAuth 免令牌登录或 PAT 登录、验证步骤、常用提示词示例、最小权限 scope 选择与常见故障排查并结合仓库源码说明底层认证与配置机制。前置条件开始前请确认满足以下两项已安装 OpenAI Codex支持 MCPCodex CLI 与 IDE 扩展共用同一份 MCP 配置文件~/.codex/config.toml因此只需配置一次两端同时生效。准备一个 GitHub Personal Access TokenPAT通过 GitHub PAT 创建页面 生成。远程服务器场景下PAT 是必需的认证凭据见下文远程配置。托管版远程服务器由 GitHub 官方托管地址为https://api.githubcopilot.com/mcp/基于 Streamable HTTP 协议工作。关于该传输协议的详细能力流式响应、OAuth 元数据发现、Scope Challenge、自定义路径等可参考仓库文档 docs/streamable-http.md关于远程服务器支持的完整工具集与请求头见 docs/remote-server.md。方案一连接远程托管服务器零本地部署远程服务器由 GitHub 官方托管无需安装任何二进制、无需启动本地进程是起步最快的方式。远程服务器基于本仓库代码构建并持续同步更新见 docs/remote-server.md 的说明同时额外提供部分仅远程可用的工具。通过配置文件接入编辑~/.codex/config.tomlCLI 与 IDE 扩展共享加入以下内容[mcp_servers.github] url https://api.githubcopilot.com/mcp/ # 用你的真实 PAT最小权限 scope替换。切勿提交到版本库。 bearer_token_env_var GITHUB_PAT_TOKEN配置说明表名必须是[mcp_servers.github]。若表名拼写错误或 TOML 语法有误Codex 将无法发现该服务器见下文故障排查表。bearer_token_env_var指定承载环境变量的名字Codex 会在请求时读取该环境变量的值作为Authorization: Bearer token请求头。该选项对于 PAT 认证访问托管服务器是必需的。通过 Codex CLI 接入也可以在终端中直接使用 Codex 自带命令添加效果与编辑配置文件等价codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN安全存储 PAT不要在配置里硬编码安全存储 PAT 的推荐做法将令牌存入.env文件避免直接写入配置文件GITHUB_PAT_TOKENghp_your_token_here将.env加入.gitignore防止误提交echo -e .env .gitignore启动 Codex 前通过环境加载如set -a; source .env; set a或使用 direnv 等工具使GITHUB_PAT_TOKEN进入 Codex 进程环境。远程服务器还支持通过请求头精确控制暴露的工具例如X-MCP-Toolsets、X-MCP-Tools、X-MCP-Readonly等与本地服务器的--toolsets/--tools/--read-only配置一一对应完整对应关系见 docs/server-configuration.md 的快速参考表。如果你希望远程接入时只开放某些工具集可以在 Codex 的config.toml中为[mcp_servers.github]配置额外请求头[mcp_servers.github] url https://api.githubcopilot.com/mcp/ bearer_token_env_var GITHUB_PAT_TOKEN headers { X-MCP-Toolsets repos,issues,pull_requests }方案二本地 Docker 自托管OAuth 免令牌或 PAT如果你希望数据与请求完全运行在本机、由自己掌控可以使用官方 Docker 镜像ghcr.io/github/github-mcp-server自托管本地实例。本仓库 README 中明确该镜像为公开镜像若拉取报错可能是 token 过期可先执行docker logout ghcr.io再试。本地服务器相关的权威 schema 请参考 OpenAI Codex 官方 MCP 配置文档本仓库 docs/oauth-login.md 详细说明了本地 OAuth 登录的完整机制。方式 AOAuth 浏览器登录推荐无需创建令牌在 github.com 上官方镜像已内置注册好的 OAuth 应用凭据你无需提供任何 client ID——服务器首次使用时会在浏览器中引导完成授权令牌仅保存在内存中不落盘。由于容器无法访问宿主机的随机回环端口Docker 部署必须发布一个固定的回调端口到 loopback。官方应用注册的回调 URL 恰好使用 8085 端口因此推荐固定使用 8085[mcp_servers.github] command docker args [run, -i, --rm, -p, 127.0.0.1:8085:8085, -e, GITHUB_OAUTH_CALLBACK_PORT, ghcr.io/github/github-mcp-server] env { GITHUB_OAUTH_CALLBACK_PORT 8085 }这里-p 127.0.0.1:8085:8085只将端口发布到 loopback容器内部回调监听全部网卡若发布到0.0.0.0会把授权码暴露到局域网服务器在容器内绑定端口时会输出警告提醒这一点。另外固定端口一旦被占用服务器会直接报错停止而非静默降级为设备码流程因为一个你无法占用的端口可能正被其他进程用于接收重定向——此时请释放端口或改用其他--oauth-callback-port值。这两个安全属性在 docs/oauth-login.md 的 Docker 一节中有明确说明。容器无法打开宿主浏览器因此授权 URL 会通过 MCP 客户端的 URL 引导URL elicitation或首次工具响应中的消息传递给你授权完成后浏览器会访问localhost:8085由 Docker 转发进容器完成回调。原生二进制流程无需固定端口直接运行github-mcp-server stdio见 cmd/github-mcp-server/main.go会使用随机回调端口并自动打开浏览器在 github.com 官方构建下无需任何额外参数。该流程与 headless/设备码回退、GitHub Enterprise 支持、自带 OAuth/GitHub App 的完整细节请参阅 docs/oauth-login.md。方式 B使用 PAT 认证优先级高于 OAuthPAT 认证优先于 OAuth若同时设置了令牌环境变量服务器将直接使用令牌而跳过 OAuth 流程该逻辑在 cmd/github-mcp-server/main.go 的 stdio 入口与 docs/oauth-login.md 的配置参考中均有体现。[mcp_servers.github] command docker args [run, -i, --rm, -e, GITHUB_PERSONAL_ACCESS_TOKEN, ghcr.io/github/github-mcp-server] env { GITHUB_PERSONAL_ACCESS_TOKEN ghp_your_token_here }本地服务器同样可以通过--toolsets/GITHUB_TOOLSETS、--tools/GITHUB_TOOLS等控制暴露的工具面未指定时使用默认工具集context、issues、pull_requests、repos、users见 README.md 与 docs/server-configuration.md。验证连接启动 CodexCLI 或 IDE后按以下步骤确认接入成功在 TUI 中运行/mcp命令或在 IDE 的 MCP 面板中确认github服务器已列出并暴露了工具。向 Codex 提问List my GitHub repositories列出我的 GitHub 仓库。如果工具缺失依次排查检查令牌有效性与 scope 是否足够确认配置表名正确为[mcp_servers.github]无拼写错误、TOML 语法正确。提示在 Codex 界面中使用/mcp可以查看全部可用的 GitHub 工具及其描述。接入后的典型用法配置完成后Codex 即可直接与 GitHub 交互。它会自动使用默认工具集也可以按 README.md 中的说明自定义工具集。以下提示词覆盖常见场景仓库操作Repository OperationsList my GitHub repositoriesShow me recent issues in [owner/repo]Create a new issue in [owner/repo] titled Bug: fix login拉取请求Pull RequestsList open pull requests in [owner/repo]Show me the diff for PR #123Add a comment to PR #123: LGTM, approvedActions 与工作流Actions WorkflowsShow me recent workflow runs in [owner/repo]Trigger the deploy workflow in [owner/repo]GistCreate a gist with this code snippetList my gists这些能力背后对应仓库 pkg/github 下的具体工具实现如issues.go、pullrequests.go、actions.go、gists.go等每个工具都声明了所需的 OAuth scope 与参数Codex 会在调用时按需使用。为 PAT 选择最小 scope工具所需的 scope 与服务器支持的 OAuth scope 一一对应。仓库 pkg/scopes/scopes.go 定义了全部受支持的 scope 常量例如repo、read:org、gist、workflow、project、security_events等并给出父级 scope 隐式覆盖子级 scope 的层级关系如repo覆盖public_repo与security_events。针对 Codex 场景的最小实用 scope 组合按需增减repo—— 通用仓库操作读取私有仓库内容、管理 Issue/PR 等workflow—— 需要 Actions 工作流访问权限时read:org—— 需要访问组织级资源时project—— 需要操作经典项目看板时gist—— 需要使用 Gist 工具时遵循最小权限原则仅在某个工具请求因权限不足失败时再追加对应 scope。例如仅当创建 Gist 被拒绝时才补充gist仅当触发工作流失败时才补充workflow。常见故障排查问题可能原因解决办法认证失败PAT 缺失或 scope 不足重新生成 PAT确保包含reposcope401 Unauthorized远程服务器令牌过期或被吊销创建新 PAT更新bearer_token_env_var指向的环境变量服务器未列出表名错误或 TOML 语法错误使用正确的[mcp_servers.github]校验 TOML 格式工具缺失 / 零工具PAT scope 不足按需补充 scopeworkflow、gist 等令牌泄露风险令牌被误提交到版本库轮换令牌将相关文件加入.gitignore安全最佳实践绝不将令牌提交进版本控制系统配置、.env、日志都不行定期轮换令牌降低泄露影响面一开始就严格限制 scope仅在确有必要时扩容及时从 GitHub 账号中删除不再使用的 PAT。参考资料远程服务器地址https://api.githubcopilot.com/mcp/本地 OAuth 登录完整机制PKCE、设备码回退、自带 App、GHES/ghe.comdocs/oauth-login.md远程服务器工具集与请求头选项docs/remote-server.mdStreamable HTTP 模式与自托管 HTTP 服务器docs/streamable-http.md本地服务器配置快速参考工具集/工具/只读模式等docs/server-configuration.md项目 README 与高级配置选项README.mdOpenAI Codex MCP 官方文档https://developers.openai.com/codex/mcp发布二进制GitHub Releases 页面见仓库 README【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 OpenAI Codex 中安装与配置 GitHub MCP Server：远程托管与本地 Docker 双方案实战
在 OpenAI Codex 中安装与配置 GitHub MCP Server远程托管与本地 Docker 双方案实战【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server本篇指南讲解如何在 OpenAI CodexCLI 与 IDE 扩展中接入 GitHub MCP Server使 Codex 通过自然语言直接操作 GitHub 仓库、Issue、Pull Request、Actions 工作流与 Gist。文章完整覆盖远程托管服务器的零本地依赖接入方式PAT 认证、本地 Docker 自托管方式OAuth 免令牌登录或 PAT 登录、验证步骤、常用提示词示例、最小权限 scope 选择与常见故障排查并结合仓库源码说明底层认证与配置机制。前置条件开始前请确认满足以下两项已安装 OpenAI Codex支持 MCPCodex CLI 与 IDE 扩展共用同一份 MCP 配置文件~/.codex/config.toml因此只需配置一次两端同时生效。准备一个 GitHub Personal Access TokenPAT通过 GitHub PAT 创建页面 生成。远程服务器场景下PAT 是必需的认证凭据见下文远程配置。托管版远程服务器由 GitHub 官方托管地址为https://api.githubcopilot.com/mcp/基于 Streamable HTTP 协议工作。关于该传输协议的详细能力流式响应、OAuth 元数据发现、Scope Challenge、自定义路径等可参考仓库文档 docs/streamable-http.md关于远程服务器支持的完整工具集与请求头见 docs/remote-server.md。方案一连接远程托管服务器零本地部署远程服务器由 GitHub 官方托管无需安装任何二进制、无需启动本地进程是起步最快的方式。远程服务器基于本仓库代码构建并持续同步更新见 docs/remote-server.md 的说明同时额外提供部分仅远程可用的工具。通过配置文件接入编辑~/.codex/config.tomlCLI 与 IDE 扩展共享加入以下内容[mcp_servers.github] url https://api.githubcopilot.com/mcp/ # 用你的真实 PAT最小权限 scope替换。切勿提交到版本库。 bearer_token_env_var GITHUB_PAT_TOKEN配置说明表名必须是[mcp_servers.github]。若表名拼写错误或 TOML 语法有误Codex 将无法发现该服务器见下文故障排查表。bearer_token_env_var指定承载环境变量的名字Codex 会在请求时读取该环境变量的值作为Authorization: Bearer token请求头。该选项对于 PAT 认证访问托管服务器是必需的。通过 Codex CLI 接入也可以在终端中直接使用 Codex 自带命令添加效果与编辑配置文件等价codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN安全存储 PAT不要在配置里硬编码安全存储 PAT 的推荐做法将令牌存入.env文件避免直接写入配置文件GITHUB_PAT_TOKENghp_your_token_here将.env加入.gitignore防止误提交echo -e .env .gitignore启动 Codex 前通过环境加载如set -a; source .env; set a或使用 direnv 等工具使GITHUB_PAT_TOKEN进入 Codex 进程环境。远程服务器还支持通过请求头精确控制暴露的工具例如X-MCP-Toolsets、X-MCP-Tools、X-MCP-Readonly等与本地服务器的--toolsets/--tools/--read-only配置一一对应完整对应关系见 docs/server-configuration.md 的快速参考表。如果你希望远程接入时只开放某些工具集可以在 Codex 的config.toml中为[mcp_servers.github]配置额外请求头[mcp_servers.github] url https://api.githubcopilot.com/mcp/ bearer_token_env_var GITHUB_PAT_TOKEN headers { X-MCP-Toolsets repos,issues,pull_requests }方案二本地 Docker 自托管OAuth 免令牌或 PAT如果你希望数据与请求完全运行在本机、由自己掌控可以使用官方 Docker 镜像ghcr.io/github/github-mcp-server自托管本地实例。本仓库 README 中明确该镜像为公开镜像若拉取报错可能是 token 过期可先执行docker logout ghcr.io再试。本地服务器相关的权威 schema 请参考 OpenAI Codex 官方 MCP 配置文档本仓库 docs/oauth-login.md 详细说明了本地 OAuth 登录的完整机制。方式 AOAuth 浏览器登录推荐无需创建令牌在 github.com 上官方镜像已内置注册好的 OAuth 应用凭据你无需提供任何 client ID——服务器首次使用时会在浏览器中引导完成授权令牌仅保存在内存中不落盘。由于容器无法访问宿主机的随机回环端口Docker 部署必须发布一个固定的回调端口到 loopback。官方应用注册的回调 URL 恰好使用 8085 端口因此推荐固定使用 8085[mcp_servers.github] command docker args [run, -i, --rm, -p, 127.0.0.1:8085:8085, -e, GITHUB_OAUTH_CALLBACK_PORT, ghcr.io/github/github-mcp-server] env { GITHUB_OAUTH_CALLBACK_PORT 8085 }这里-p 127.0.0.1:8085:8085只将端口发布到 loopback容器内部回调监听全部网卡若发布到0.0.0.0会把授权码暴露到局域网服务器在容器内绑定端口时会输出警告提醒这一点。另外固定端口一旦被占用服务器会直接报错停止而非静默降级为设备码流程因为一个你无法占用的端口可能正被其他进程用于接收重定向——此时请释放端口或改用其他--oauth-callback-port值。这两个安全属性在 docs/oauth-login.md 的 Docker 一节中有明确说明。容器无法打开宿主浏览器因此授权 URL 会通过 MCP 客户端的 URL 引导URL elicitation或首次工具响应中的消息传递给你授权完成后浏览器会访问localhost:8085由 Docker 转发进容器完成回调。原生二进制流程无需固定端口直接运行github-mcp-server stdio见 cmd/github-mcp-server/main.go会使用随机回调端口并自动打开浏览器在 github.com 官方构建下无需任何额外参数。该流程与 headless/设备码回退、GitHub Enterprise 支持、自带 OAuth/GitHub App 的完整细节请参阅 docs/oauth-login.md。方式 B使用 PAT 认证优先级高于 OAuthPAT 认证优先于 OAuth若同时设置了令牌环境变量服务器将直接使用令牌而跳过 OAuth 流程该逻辑在 cmd/github-mcp-server/main.go 的 stdio 入口与 docs/oauth-login.md 的配置参考中均有体现。[mcp_servers.github] command docker args [run, -i, --rm, -e, GITHUB_PERSONAL_ACCESS_TOKEN, ghcr.io/github/github-mcp-server] env { GITHUB_PERSONAL_ACCESS_TOKEN ghp_your_token_here }本地服务器同样可以通过--toolsets/GITHUB_TOOLSETS、--tools/GITHUB_TOOLS等控制暴露的工具面未指定时使用默认工具集context、issues、pull_requests、repos、users见 README.md 与 docs/server-configuration.md。验证连接启动 CodexCLI 或 IDE后按以下步骤确认接入成功在 TUI 中运行/mcp命令或在 IDE 的 MCP 面板中确认github服务器已列出并暴露了工具。向 Codex 提问List my GitHub repositories列出我的 GitHub 仓库。如果工具缺失依次排查检查令牌有效性与 scope 是否足够确认配置表名正确为[mcp_servers.github]无拼写错误、TOML 语法正确。提示在 Codex 界面中使用/mcp可以查看全部可用的 GitHub 工具及其描述。接入后的典型用法配置完成后Codex 即可直接与 GitHub 交互。它会自动使用默认工具集也可以按 README.md 中的说明自定义工具集。以下提示词覆盖常见场景仓库操作Repository OperationsList my GitHub repositoriesShow me recent issues in [owner/repo]Create a new issue in [owner/repo] titled Bug: fix login拉取请求Pull RequestsList open pull requests in [owner/repo]Show me the diff for PR #123Add a comment to PR #123: LGTM, approvedActions 与工作流Actions WorkflowsShow me recent workflow runs in [owner/repo]Trigger the deploy workflow in [owner/repo]GistCreate a gist with this code snippetList my gists这些能力背后对应仓库 pkg/github 下的具体工具实现如issues.go、pullrequests.go、actions.go、gists.go等每个工具都声明了所需的 OAuth scope 与参数Codex 会在调用时按需使用。为 PAT 选择最小 scope工具所需的 scope 与服务器支持的 OAuth scope 一一对应。仓库 pkg/scopes/scopes.go 定义了全部受支持的 scope 常量例如repo、read:org、gist、workflow、project、security_events等并给出父级 scope 隐式覆盖子级 scope 的层级关系如repo覆盖public_repo与security_events。针对 Codex 场景的最小实用 scope 组合按需增减repo—— 通用仓库操作读取私有仓库内容、管理 Issue/PR 等workflow—— 需要 Actions 工作流访问权限时read:org—— 需要访问组织级资源时project—— 需要操作经典项目看板时gist—— 需要使用 Gist 工具时遵循最小权限原则仅在某个工具请求因权限不足失败时再追加对应 scope。例如仅当创建 Gist 被拒绝时才补充gist仅当触发工作流失败时才补充workflow。常见故障排查问题可能原因解决办法认证失败PAT 缺失或 scope 不足重新生成 PAT确保包含reposcope401 Unauthorized远程服务器令牌过期或被吊销创建新 PAT更新bearer_token_env_var指向的环境变量服务器未列出表名错误或 TOML 语法错误使用正确的[mcp_servers.github]校验 TOML 格式工具缺失 / 零工具PAT scope 不足按需补充 scopeworkflow、gist 等令牌泄露风险令牌被误提交到版本库轮换令牌将相关文件加入.gitignore安全最佳实践绝不将令牌提交进版本控制系统配置、.env、日志都不行定期轮换令牌降低泄露影响面一开始就严格限制 scope仅在确有必要时扩容及时从 GitHub 账号中删除不再使用的 PAT。参考资料远程服务器地址https://api.githubcopilot.com/mcp/本地 OAuth 登录完整机制PKCE、设备码回退、自带 App、GHES/ghe.comdocs/oauth-login.md远程服务器工具集与请求头选项docs/remote-server.mdStreamable HTTP 模式与自托管 HTTP 服务器docs/streamable-http.md本地服务器配置快速参考工具集/工具/只读模式等docs/server-configuration.md项目 README 与高级配置选项README.mdOpenAI Codex MCP 官方文档https://developers.openai.com/codex/mcp发布二进制GitHub Releases 页面见仓库 README【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考