新手上路（四）：Codex MCP 实战——让 Codex 连接外部世界

您^_^2026-05-31 8:24

Codex 连不上数据库和 GitHub？6 个 MCP 服务器完整配置，复制粘贴即用

Windows 10/11 · Codex CLI v0.130.0 · DeepSeek V4 Pro · dsv4-cc-proxy-tray · 2026-05-29 · 🟡 中度时效

一、这篇教程解决什么问题

一句话定位：Codex 在终端里很能干，但它看不见你的 GitHub、连不上你的数据库、搜不了实时信息。MCP（模型上下文协议）就是给 Codex 装上"眼睛和手"------这篇教你配 6 个实测可用的 MCP 服务器，让 Codex 从终端工具升级为全栈开发代理。

跳读指南 ：只想抄一个配置的跳到 [第三节 6 个 MCP 服务器实战](#第三节 6 个 MCP 服务器实战)，每个给完整的 TOML 配置。配好了但工具不显示的跳到 [Debug 章节](#Debug 章节)。国内 npx 拉包超时的先看 [2.1 节](#2.1 节)。

阅读前提：

  • 已完成安全快速上手篇或（一）（二）（三）期，Codex 能正常启动
  • Node.js 环境正常（npx --version 能输出）
  • GitHub MCP 需要一个 Personal Access Token（不用 GitHub 可以不配）

读完能得到什么：

  • 6 个 MCP 服务器的完整 TOML 配置，复制粘贴即用
  • 理解 Codex MCP 和 Claude Code MCP 的配置差异------两边都用的读者不用翻文档
  • 知道国内环境下 npx 超时、工具不显示等常见坑的解决方案

二、MCP 是什么------30 秒版

不解释协议细节，只说你为什么需要它：

复制代码 
没有 MCP 的 Codex：只能读你项目里的文件，执行终端命令
有 MCP 的 Codex：能操作 GitHub Issue、直连数据库查表、
               实时搜索网页、抓取文档、跨会话记住上下文

MCP 是一个开放协议，Codex 和 Claude Code 都支持。核心思想一样------"AI 通过标准接口调用外部工具"------但配置语法不同：

维度 Codex Claude Code
配置文件 config.toml（TOML 格式） settings.json（JSON 格式）
配置位置 [mcp_servers.<id>] 块 "mcpServers" 键
添加命令 codex mcp add claude mcp add
查看工具 /mcp /mcp

好消息：同一个 MCP 服务器包（如 @anthropic/mcp-server-github），两边都能用。你只需要把配置语法从 JSON 翻译成 TOML。

2.1 开始之前：国内用户必须先配 npx 镜像

本文 6 个服务器中有 5 个通过 npx -y @xxx/xxx 启动，Codex 每次启动都会自动拉包。不配镜像的话大概率超时------表现为工具列表为空。

powershell 复制代码 
npm config set registry https://registry.npmmirror.com

验证：

powershell 复制代码 
npx -y @modelcontextprotocol/server-filesystem --version 2>&1 | Select-Object -First 3
# 如果能看到版本信息或帮助文本（而不是超时报错），说明镜像生效

三、6 个 MCP 服务器实战

以下 6 个服务器全部实测可用。每个给三样东西：是什么 → 完整 TOML 配置 → 试一下。

3.1 Filesystem------让 Codex 安全读写指定目录

是什么：允许 Codex 在指定目录内读写文件。配合 Sandbox 机制精确控制 AI 的文件访问范围。

为什么需要它？Codex 本身已经能读写工作目录内的文件------Filesystem MCP 的核心价值是指定工作目录之外的安全访问路径，比如 monorepo 的共享库目录。

完整 TOML 配置：

toml 复制代码 
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "D:\\shared-libs", "D:\\assets"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60

试一下：

在 Codex 中输入：

复制代码 
用 filesystem MCP 列出 D:\shared-libs 目录下的所有文件

3.2 GitHub------让 Codex 操作 Issue、PR 和仓库

是什么：让 Codex 直接在终端里创建 Issue、查看 PR、搜索代码。

前置准备：

  1. 打开 github.com/settings/tokens → Generate new token (classic)
  2. 勾选 repo、read:org、read:user 权限
  3. 复制 Token（格式 ghp_xxxxxxxx）

完整 TOML 配置：

toml 复制代码 
[mcp_servers.github]
command = "npx"
args = ["-y", "@anthropic/mcp-server-github"]
enabled = true
startup_timeout_sec = 15
tool_timeout_sec = 60

[mcp_servers.github.env]
GITHUB_TOKEN = "ghp_你的GitHub-Token"

不要把 Token 直接写在 args 里（--token ghp_xxx）------写在 env 块中不会出现在进程列表里。

试一下：

复制代码 
用 GitHub MCP 在我自己的仓库里创建一个 Issue，标题是 "MCP 测试------请忽略"

3.3 Postgres------让 Codex 直连数据库

是什么：让 Codex 连接 PostgreSQL 数据库，查表结构、执行只读查询、分析数据。

前置准备：一个可访问的 PostgreSQL 实例（本地或远程均可）。

完整 TOML 配置：

toml 复制代码 
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@anthropic/mcp-server-postgres", "postgresql://用户名:密码@localhost:5432/数据库名"]
enabled = true
startup_timeout_sec = 15
tool_timeout_sec = 30

建议创建只读用户给 Codex 使用，避免 AI 执行意外的写操作。

试一下：

复制代码 
用 Postgres MCP 列出我数据库里的所有表名

3.4 Memory------让 Codex 跨会话记住上下文

是什么：给 Codex 装一个持久化记忆。每次会话结束时自动存储关键信息，下次会话启动时自动召回。基于 SQLite + 知识图谱，不需要外部数据库。

Codex 默认每次新会话是"失忆"的------Memory MCP 解决了这个问题。

完整 TOML 配置：

toml 复制代码 
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

试一下：

在 Codex 中输入：

复制代码 
记住这个信息：我的项目 PostgreSQL 连接串是 postgresql://admin:pass123@localhost:5432/myapp

然后 /new 开一个新会话，问：

复制代码 
我们之前讨论过的 PostgreSQL 连接串是什么？

3.5 Brave Search------让 Codex 实时搜索网页

是什么：让 Codex 在对话中直接搜索网页和新闻。需要 Brave Search API Key（免费额度每月 2000 次）。

前置准备：

  1. 打开 brave.com/search/api → 注册获取 API Key
  2. Key 格式：BSA-xxxxxxxx

完整 TOML 配置：

toml 复制代码 
[mcp_servers.brave_search]
command = "npx"
args = ["-y", "@anthropic/mcp-server-brave-search"]
enabled = true
startup_timeout_sec = 15
tool_timeout_sec = 30

[mcp_servers.brave_search.env]
BRAVE_API_KEY = "BSA-你的Brave-API-Key"

试一下：

复制代码 
搜索 "Codex CLI MCP 配置教程 2026"，用中文总结前 3 条结果

3.6 Fetch------让 Codex 抓取任意网页内容

是什么：让 Codex 抓取指定 URL 的内容并转为 Markdown。配合 Brave Search 效果最好------先搜到链接，再抓取全文。

完整 TOML 配置：

toml 复制代码 
[mcp_servers.fetch]
command = "npx"
args = ["-y", "@anthropic/mcp-server-fetch"]
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60

试一下：

复制代码 
抓取这个页面的内容并总结：https://developers.openai.com/codex/config-reference

3.7 Windows 用户特别注意：npx 命令的坑

坑：npx 找不到命令

toml 复制代码 
# ❌ Windows 上某些 Node 安装方式下 npx 直接调用失败
[mcp_servers.filesystem]
command = "npx"

# ✅ 用 cmd /c 包装（仅在直接调用失败时使用）
[mcp_servers.filesystem]
command = "cmd"
args = ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:\\shared-libs"]

是否需要 cmd /c？取决于你的 Node.js 安装方式。用 nvm-windows 或 fnm 管理的 Node，npx 通常在 PATH 中，直接 command = "npx" 就能用。遇到 'npx' is not recognized 再改成 cmd /c npx。

四、CLI 命令行管理 MCP 服务器

除了直接编辑 config.toml，Codex 还提供了命令行方式管理 MCP：

powershell 复制代码 
# 添加一个 MCP 服务器（自动写入 config.toml）
codex mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem D:\workspace

# 列出所有已配置的 MCP 服务器及其状态
codex mcp list

# 查看某个服务器的详细配置
codex mcp get github

# 移除一个 MCP 服务器
codex mcp remove old-server

codex mcp add 会自动写入 config.toml，不需要手动编辑文件。适合快速试一个服务器。

在 Codex TUI 中，打 /mcp 可以查看当前已加载的工具列表和服务器状态。配好一个服务器后，用 /mcp 确认工具是否出现------这是最快的验证方式。

Debug 章节

Debug #1 --- MCP 配好了但工具不显示

报错现象

打 /mcp 列表是空的。对话中让 Codex "用 GitHub MCP 创建 Issue"，Codex 回复 "我没有 GitHub 工具"。

根因

两种最常见：1) npx 启动 MCP 服务器超时（国内网络问题）；2) TOML 语法错误或 enabled = false。

一览对比表
对比维度 修复前 修复后
/mcp 输出 空 列出已配置的服务器和工具
根因 npx 超时或配置语法错误 npx 镜像生效 + TOML 正确
代码修复

Step 1 --- 确认 npm 镜像已配：

powershell 复制代码 
npm config get registry
# 预期：https://registry.npmmirror.com

Step 2 --- 手动测试 MCP 包能否拉取：

powershell 复制代码 
npx -y @anthropic/mcp-server-github --help 2>&1 | Select-Object -First 5

超时 = 镜像问题。正常输出 = 包没问题。

Step 3 --- 用 codex mcp list 确认配置被读取：

powershell 复制代码 
codex mcp list

Step 4 --- 关掉 Codex 重开，打 /mcp 查看。

验证

打 /mcp，看到你配的服务器和工具列表。选一个工具在对话中试用。

Debug #2 --- npx 拉包超时

报错现象
复制代码 
npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/... failed
根因

npx 从 npm 官方源拉包超时。

代码修复

Step 1 --- 配镜像：

powershell 复制代码 
npm config set registry https://registry.npmmirror.com

Step 2 --- 清 npx 缓存：

powershell 复制代码 
Remove-Item -Recurse -Force $env:USERPROFILE\AppData\Local\npm-cache\_npx -ErrorAction SilentlyContinue

Step 3 --- 如果仍然慢，全局安装一次让包预缓存：

powershell 复制代码 
npm install -g @anthropic/mcp-server-github

全局安装后 npx 从本地缓存启动，不再每次拉包。

验证
powershell 复制代码 
npx -y @anthropic/mcp-server-github --help 2>&1 | Select-Object -First 3
# 几秒内输出帮助信息 = 修复成功

Debug #3 --- MCP 工具提示权限不足

报错现象
复制代码 
Error: permission denied. Access to this tool requires approval
根因

MCP 工具的审批模式需要用户手动授权。

代码修复

在 config.toml 中设置 MCP 工具的默认审批模式：

toml 复制代码 
[mcp_servers.github]
command = "npx"
args = ["-y", "@anthropic/mcp-server-github"]
enabled = true
default_tools_approval_mode = "auto"   # 自动通过，不弹窗
# "prompt" = 弹窗确认；"approve" = 需要批准

同时确保全局 approval_policy 不是 untrusted。

验证

重新启动 Codex，使用 GitHub MCP 创建测试 Issue。不弹权限提示 = 生效。

Debug #4 --- MCP 服务器启动后立即断开

报错现象
复制代码 
MCP server 'github' exited unexpectedly
MCP error: stdin closed
根因

MCP 服务器进程崩溃。常见：环境变量缺失（如 GITHUB_TOKEN 没设）、Node.js 版本太低、包版本不兼容。

代码修复

Step 1 --- 手动启动看报什么错：

powershell 复制代码 
$env:GITHUB_TOKEN = "ghp_你的Token"
npx -y @anthropic/mcp-server-github

观察输出：

  • GITHUB_TOKEN not set → 检查 env 块写法
  • Cannot find module → 包版本问题，加 @latest

Step 2 --- 确认 Node.js 版本：

powershell 复制代码 
node --version
# 需要 v18+
验证

手动启动不报错 + Codex 里 /mcp 看到工具 = 修复成功。

Debug #5 --- Cannot find module 或包版本冲突

报错现象
复制代码 
Error: Cannot find module '@anthropic/mcp-server-github'
根因

npx 缓存了损坏的包或旧版本。

代码修复
powershell 复制代码 
# 1. 清空 npx 缓存
Remove-Item -Recurse -Force $env:USERPROFILE\AppData\Local\npm-cache\_npx -ErrorAction SilentlyContinue

# 2. 强制拉最新版
npx -y @anthropic/mcp-server-github@latest --help

# 3. 如果仍有问题，全局重装
npm install -g @anthropic/mcp-server-github@latest
验证
powershell 复制代码 
npx -y @anthropic/mcp-server-github@latest --help 2>&1 | Select-Object -First 3
# 无 Cannot find module 报错

五、速查卡

5.1 6 个 MCP 服务器一览

服务器 包名 需要 API Key？ 核心工具
Filesystem @modelcontextprotocol/server-filesystem 否 read_file, write_file, list_directory
GitHub @anthropic/mcp-server-github 是（GITHUB_TOKEN） create_issue, search_repositories, get_file_contents
Postgres @anthropic/mcp-server-postgres 否 query, list_tables, describe_table
Memory @modelcontextprotocol/server-memory 否 create_entities, search_nodes, open_nodes
Brave Search @anthropic/mcp-server-brave-search 是（BRAVE_API_KEY） brave_web_search, brave_news_search
Fetch @anthropic/mcp-server-fetch 否 fetch, fetch_markdown

5.2 命令速查

操作 命令
添加服务器 codex mcp add <name> -- npx -y <package>
查看全部 codex mcp list
查看单个 codex mcp get <name>
删除服务器 codex mcp remove <name>
TUI 中查看 /mcp
配镜像 npm config set registry https://registry.npmmirror.com
清 npx 缓存 Remove-Item -Recurse -Force $env:USERPROFILE\AppData\Local\npm-cache\_npx

5.3 常见报错 → 解决方案

报错 解决
MCP 工具不显示 检查 npm 镜像 + codex mcp list + 手动测试包，见 [Debug #1](#1 npx 拉包超时 配镜像 + 清缓存 + 全局安装，见 Debug #2 权限不足 设 default_tools_approval_mode = "auto"，见 Debug #3 服务器启动后断开 手动启动排查 + 检查 Node 版本 + env，见 Debug #4 Cannot find module 清 npx 缓存 + 强制 @latest，见 Debug #5)
npx 拉包超时 配镜像 + 清缓存 + 全局安装，见 [Debug #2](#1 npx 拉包超时 配镜像 + 清缓存 + 全局安装，见 Debug #2 权限不足 设 default_tools_approval_mode = "auto"，见 Debug #3 服务器启动后断开 手动启动排查 + 检查 Node 版本 + env，见 Debug #4 Cannot find module 清 npx 缓存 + 强制 @latest，见 Debug #5)
权限不足 设 default_tools_approval_mode = "auto"，见 [Debug #3](#1 npx 拉包超时 配镜像 + 清缓存 + 全局安装，见 Debug #2 权限不足 设 default_tools_approval_mode = "auto"，见 Debug #3 服务器启动后断开 手动启动排查 + 检查 Node 版本 + env，见 Debug #4 Cannot find module 清 npx 缓存 + 强制 @latest，见 Debug #5)
服务器启动后断开 手动启动排查 + 检查 Node 版本 + env，见 [Debug #4](#1 npx 拉包超时 配镜像 + 清缓存 + 全局安装，见 Debug #2 权限不足 设 default_tools_approval_mode = "auto"，见 Debug #3 服务器启动后断开 手动启动排查 + 检查 Node 版本 + env，见 Debug #4 Cannot find module 清 npx 缓存 + 强制 @latest，见 Debug #5)
Cannot find module 清 npx 缓存 + 强制 @latest，见 [Debug #5](#1 npx 拉包超时 配镜像 + 清缓存 + 全局安装，见 Debug #2 权限不足 设 default_tools_approval_mode = "auto"，见 Debug #3 服务器启动后断开 手动启动排查 + 检查 Node 版本 + env，见 Debug #4 Cannot find module 清 npx 缓存 + 强制 @latest，见 Debug #5)

六、扩展阅读

参考文献

  1. DeepWiki --- Codex MCP Server Configuration --- Codex MCP 配置字段完整参考
  2. Windows下Codex CLI与MCP深度整合 (CSDN) --- Windows 特有的 TOML 路径处理和 cmd /c 包装技巧
  3. @anthropic/mcp-server-github (npm) --- GitHub MCP 官方包
  4. @anthropic/mcp-server-brave-search (npm) --- Brave Search MCP 官方包
  5. @modelcontextprotocol/server-memory (npm) --- Memory MCP 官方包
  6. @modelcontextprotocol/server-filesystem (npm) --- Filesystem MCP 官方包
  7. MCP Setup --- Codex Developer Toolkit --- 英文 MCP 配置实战指南
相关推荐
veminhe1 小时前
claude-code下载安装与使用
人工智能
波动几何1 小时前
工作流重构技能的社会影响
人工智能
AI产品库1 小时前
2026年5月30日AI简报 | OpenAI生物防御 | Anthropic融资 | 天津智博会 | 戴尔AI服务器 | GitHub Copilot自主化
人工智能
愚公搬代码1 小时前
【愚公系列】《AI漫剧创作一本通》037-AI漫剧未来展望（视频Agent与创作方式变革）
人工智能
开开心心就好1 小时前
小白友好的程序联网封锁实用工具
windows·eureka·计算机外设·rabbitmq·word·excel·csdn开发云
陆业聪1 小时前
WebView与原生JS交互：JSBridge设计模式与安全实践
人工智能·aigc
吃好睡好便好1 小时前
矩阵的左除和右除
人工智能·学习·线性代数·算法·矩阵
John_ToDebug1 小时前
Claude Code Agent 使用最佳实践与底层机制全解
人工智能·经验分享·ai
阿部多瑞 ABU1 小时前
一次针对大语言模型的“虚构历史前提注入”红队测试实录：当AI相信了不存在的对话历史
网络·人工智能·安全
热门推荐
01GitHub 镜像站点02【AI】2026 年具身智能模型和世界模型总结03DeepSeek V4 + Claude Code thinking mode 400 错误修复方案04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05Codex 接入 DeepSeek API 完整配置文档06裂开！ChatGPT 居然开始要手机号验证，附详细解决方法07CC-Switch & Claude 基于 Linux 服务器安装使用指南08几个好用的ip纯净度检测网站09CC-Switch 全平台下载、安装与使用全指南（Windows/macOS/Linux）10API Key 登录 Codex 也能用插件了，还支持会话删除和导出