Codex CLI教程（八） | MCP 之 GitHub

前言
[第一章：MCP 接入前置要求](#第一章：MCP 接入前置要求)
[第二章：MCP 接入方式](#第二章：MCP 接入方式)
- [2.1 方式一：本地接入](#2.1 方式一：本地接入)
- [2.2 方式二：远程接入（推荐）](#2.2 方式二：远程接入（推荐）)
- [2.3 GitHub PAT 怎么准备](#2.3 GitHub PAT 怎么准备)
- - [1. Repository access](#1. Repository access)
  - [2. Permissions](#2. Permissions)
  - [3. 保存 Token](#3. 保存 Token)
- [2.4 配置文件位置](#2.4 配置文件位置)
- [2.5 配完以后怎么验证](#2.5 配完以后怎么验证)
第三章：该怎么选
第四章：补充说明
- [4.1 OAuth 和 PAT 都可以用](#4.1 OAuth 和 PAT 都可以用)
- [4.2 Fine-grained PAT 不要和 classic scope 混着写](#4.2 Fine-grained PAT 不要和 classic scope 混着写)
- [4.3 不要漏掉仓库范围](#4.3 不要漏掉仓库范围)

前言

给 Codex 接入 GitHub MCP，目的很明确：让 Codex 直接访问 GitHub 能力，比如查看仓库、读取 issue、处理 pull request、检查 workflow 等。

GitHub MCP 本质上是一个面向 GitHub 能力的 MCP Server，作用是把 GitHub 的上下文和操作能力接入到 Codex 里。

第一章：MCP 接入前置要求

在正式配置之前，先准备好以下内容：

一个支持 MCP 的客户端，比如 Codex
一个可用的 GitHub 账号
一种 GitHub 认证方式

GitHub MCP 通常需要认证，常见方式有两种：

GitHub OAuth
GitHub Personal Access Token（PAT）

不过，放到 Codex 的实际配置场景里，远程接入通常直接使用 PAT ；本地接入最常见的方式也是 PAT。

如果你使用的是 Fine-grained personal access token，还需要额外注意两件事：

Repository access 要选对仓库范围
Permissions 要给够所需权限

准备好认证方式之后，就可以开始正式接入了。

第二章：MCP 接入方式

2.1 方式一：本地接入

本地接入的意思是：在本机启动一个 GitHub MCP 进程。

Codex 不会直接连接 GitHub，而是先连接这个本地 MCP 进程，再由这个进程去访问 GitHub。它的链路可以理解为：

Codex -> 本地 GitHub MCP -> GitHub

本地方式最常见的认证方式是：GitHub PAT。

典型配置结构如下：

toml 复制代码

[mcp_servers.github]
command = "你本机上 github-mcp-server 可执行文件的实际位置"
args = ["stdio"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "你的 GitHub PAT" }
startup_timeout_sec = 20

这段配置的含义如下：

command：本地 GitHub MCP Server 的启动命令
args：以 stdio 模式运行
env：通过环境变量传入 GitHub PAT
startup_timeout_sec：启动超时时间

如果你希望自己掌控本地运行方式，并且愿意使用 PAT 认证，可以考虑本地接入。

2.2 方式二：远程接入（推荐）

远程接入的意思是：不在本机启动 GitHub MCP 进程。

Codex 会直接连接 GitHub 官方托管的远程 MCP 服务。它的链路可以理解为：

Codex -> GitHub 远程 MCP

官方远程地址如下：

toml 复制代码

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
startup_timeout_sec = 20

GitHub MCP 在通用层面支持 OAuth 和 PAT 两种认证方式。

但放到 Codex 的手动配置场景里，远程接入通常直接使用 PAT，不按 OAuth 作为默认方案讲。

在 Codex 里，远程接入常见写法如下：

toml 复制代码

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"
startup_timeout_sec = 20

这段配置表示：

url：GitHub 官方托管的远程 MCP 地址
bearer_token_env_var：从环境变量中读取 GitHub Token
startup_timeout_sec：连接超时时间

如果你只是想尽快接入并开始使用，远程接入通常更适合作为默认方案。

2.3 GitHub PAT 怎么准备

如果你使用的是 GitHub PAT，建议优先选择：

Fine-grained personal access token

创建时建议这样设置。

1. Repository access

通常建议选择：

Only select repositories

然后勾选你要让 GitHub MCP 访问的仓库。

2. Permissions

基础场景下，通常先给下面这些权限：

Contents → Read and write
Issues → Read and write
Pull requests → Read and write
Metadata → Read-only
Commit statuses → Read-only

如果还要处理 GitHub Actions，再额外补：

Workflows → Read and write

3. 保存 Token

Token 生成后一般只显示一次，创建完成后要立即复制保存。

2.4 配置文件位置

Codex 的 MCP 配置通常写在：

text 复制代码

~/.codex/config.toml

Windows 下常见路径类似：

text 复制代码

C:\Users\你的用户名\.codex\config.toml

也就是说，上面的配置都应该写进这个 config.toml 文件里。

2.5 配完以后怎么验证

配置完成后，建议按下面顺序检查：

保存 config.toml
确认环境变量已经生效
重新打开 Codex
查看 GitHub MCP 是否已加载
实际测试一次调用

例如可以测试：

List my GitHub repositories
Show me open pull requests in owner/repo
Show me recent issues in owner/repo

如果这些请求能正常返回结果，说明 GitHub MCP 已经接通。

第三章：该怎么选

如果只是从使用成本来看，更建议这样理解：

想少折腾环境、尽快接入：优先选 远程接入
想自己控制本地启动链路：可以选 本地接入

也就是说：

默认推荐远程接入
本地接入更适合明确需要本地运行的人

第四章：补充说明

4.1 OAuth 和 PAT 都可以用

GitHub MCP 在通用层面支持 OAuth 和 PAT。

但在 Codex 的手动配置场景里，通常直接按 PAT 配置即可。

4.2 Fine-grained PAT 不要和 classic scope 混着写

如果你创建的是 Fine-grained personal access token，就按 GitHub 页面里的细粒度权限项来配，比如：

Contents
Issues
Pull requests

不要再写 classic token 的 repo、workflow 那套 scope 名称。

4.3 不要漏掉仓库范围

对于 Fine-grained PAT 来说，除了权限项，还要选对仓库范围。

如果目标仓库没包含进去，后面一样不能正常使用。