codex-web-search-mcp
一个模型无关的 MCP (Model Context Protocol) server,把 OpenAI Codex 的独立搜索端点
(chatgpt.com/backend-api/codex/alpha/search)封装成 Claude Code / 任意 MCP 客户端可用的联网搜索工具。
已用 Rust 全量重写为独立二进制(当前 v2.3.1,不再依赖 Node / npx):
- 后端 OpenAI Codex(免费,只要 登录态);
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
一个模型无关的 MCP (Model Context Protocol) server,把 OpenAI Codex 的独立搜索端点
(chatgpt.com/backend-api/codex/alpha/search)封装成 Claude Code / 任意 MCP 客户端可用的联网搜索工具。
已用 Rust 全量重写为独立二进制(当前 v2.3.1,不再依赖 Node / npx):
Model-independent web search & deep research MCP server for Claude Code, powered by OpenAI Codex's standalone search endpoint. Works with any model (Gemini/OpenRouter/local), zero npm dependencies.
codex logincodex_web_search、codex_web_research、web_fetch;web_fetch 自动探测中文编码(GBK/GB2312 等)、跟随 301/302 重定向,避免乱码与空正文;429 / 服务端 5xx / 网络抖动做指数退避(最多 3 次:500ms、1s);401/403 以及其它 4xx(如 400 校验失败)直接友好报错、不重试;401 且本机 auth.json 带有 refresh_token 时,自动换发新 access_token 并回写(先备份),免去手动 codex login;research 返回的来源按 ref_id/url 去重,并按域名分组展示,引用更干净;--verbose 或 CODEX_MCP_LOG=debug 把请求 URL、HTTP 状态、耗时、重试写到 stderr(绝不污染 MCP 的 stdout 管道);灵感与端点实现来自 mateusdcc/pi-gpt-search(MIT)。
Claude Code 原生的 WebSearch / WebFetch 工具绑定 Anthropic API。一旦把基座模型换成
Gemini、OpenRouter、本地模型等非 Anthropic 模型,这些工具就会失灵。
本工具直连 Codex 的独立搜索端点,与底层模型完全无关——无论客户端用哪个模型, 都能通过 MCP 工具获得实时联网搜索能力,且不消耗 GPT/Codex 的推理 token(只占用账号搜索额度,见下)。
Claude Code / 任意 MCP 客户端(任意模型)
├── codex_web_search(query) # 单步快速搜索
├── codex_web_research(...) # 多步深度研究(search→open→find→click,靠 ref_id 串联)
└── web_fetch(url) # 抓取任意 URL 纯文本(补足搜到却读不到正文的短板)
│
▼
┌─────────────────────┐
│ OpenAI Codex 搜索 │ ───────▶ /backend-api/codex/alpha/search
│ 端点(免费登录态) │
└─────────────────────┘
model 字段仅作为接口要求的标签(固定 gpt-4o),不代表实际调用 GPT。search_query / open / find / click 都是同一个端点 commands 里的并列操作,后端靠请求体的
会话 id 维持上下文,使后续 open/find/click 能解析上一次搜索返回的 ref_id。本 server 在多次
tool call 之间复用同一会话 id,并把 ref_id 暴露在来源列表里,模型即可多轮编排。[turn0searchN: 标题 → 域名] 形式(旧版是 PUA 私有区字符,已重写清理),
模型可直接拿 turn0searchN 这种 ref_id 去做 open / click。codex login,OAuth 自动把 token 写入 ~/.codex/auth.json;CODEX_ACCESS_TOKEN(可选 CODEX_ACCOUNT_ID)。没有 ChatGPT/Codex 账号、未登录、或会话过期(
401/403)时,工具会返回明确的中文报错,而不是崩溃。
成本与额度提醒:本工具不按 GPT 生成 token 计费——它调用的是 Codex 的
search端点 (/backend-api/codex/alpha/search),而非chat/completions文本生成。但每次搜索都会占用你 ChatGPT/Codex 账号的搜索额度与速率配额(服务端按账号限流,超限返回429)。要点:
- 需要有效的 ChatGPT/Codex 登录态;免费账号通常可用但频率/总量受限,高频或重度使用建议 Pro/Plus。
- 它不是「零 OpenAI 资源」:与纯本地 Playwright 类浏览器工具(完全不碰 OpenAI)不同,本工具依赖 OpenAI 搜索后端,每次调用都会消耗对应账号额度。
- 触发
401/403(凭证过期/权限不足)或429(速率超限)时,重登录或稍后重试即可。
不必手动编写
auth.json:它是codex login的 OAuth 产物,手搓无效。让codex login自动生成,或改用环境变量。
方式 1:codex login(推荐)
npm install -g @openai/codex # 国内: --registry=https://registry.npmmirror.com
codex login # 浏览器走 ChatGPT/OpenAI OAuth
登录成功后自动写入 ~/.codex/auth.json(含 tokens.access_token / tokens.account_id)。
server 会自动读取,无需额外配置。
方式 2:环境变量 CODEX_ACCESS_TOKEN(免 auth.json)
# Windows PowerShell
$env:CODEX_ACCESS_TOKEN = "你的token"
$env:CODEX_ACCOUNT_ID = "你的account_id" # 可选
# macOS / Linux
export CODEX_ACCESS_TOKEN="你的token"
export CODEX_ACCOUNT_ID="你的account_id" # 可选
凭证过期(
401/403):方式 1 重新codex login;方式 2 换新 token。
本项目是独立原生二进制,无需安装 Rust、无需 Node 即可使用。三种拿到二进制的方式:
curl -fsSL https://raw.githubusercontent.com/dhicoc/codex-web-search-mcp/main/scripts/install.sh | bash
irm https://raw.githubusercontent.com/dhicoc/codex-web-search-mcp/main/scripts/install.ps1 | iex
--write-config 可顺手生成 .mcp.json。checksums.txt(SHA-256 清单)供校验。各平台文件名见下「配置 MCP · 方式 A」。# 本仓库脚本已注入 VS 2023 环境(INCLUDE/LIB 用反斜杠,避开 LNK1181)
bash scripts/build.sh --release
# 产物: target/release/codex-web-search-mcp.exe
⚠️ 编译坑(已踩过):MSVC 的
link.exe/cl.exe只认「反斜杠 +C:\盘符」的INCLUDE/LIB路径。用正斜杠/或/c/风格会报LNK1181: 无法打开输入文件“kernel32.lib”。本脚本已处理;若手动编译,务必导出带反斜杠的INCLUDE/LIB并指向 MSVC 的Hostx64/x64/link.exe。
cargo build --release
# 产物: target/release/codex-web-search-mcp
去 Releases 下载与你平台匹配的文件, 放到任意目录即可使用——不需要 Rust、不需要 Node:
MCP 配置(把 command 换成你下载的文件路径):
{
"mcpServers": {
"codex-web-search": {
"command": "C:/path/to/codex-web-search-mcp-win32-x64.exe"
}
}
}
command 换成你下载文件的实际路径(如 /path/to/codex-web-search-mcp-darwin-universal)。/mcp)。~/.claude.json)的 mcpServers 即对所有项目生效。Rust 版是独立二进制,编译一次后直接让客户端 spawn 这个 exe(或 macOS/Linux 下的二进制)即可,不需要 Node。
{
"mcpServers": {
"codex-web-search": {
"command": "C:/path/to/codex-web-search-mcp/target/release/codex-web-search-mcp.exe"
}
}
}
command 换成 /path/to/codex-web-search-mcp/target/release/codex-web-search-mcp。/mcp)。~/.claude.json)的 mcpServers 即对所有项目生效。可选项:在 MCP 配置的
"env"里加CODEX_ACCESS_TOKEN覆盖凭证(方式 2)。若用codex login,连 exe 路径都不用配 env。
⚠️ 不要用
"command": "cmd", "args": ["/c", ...]—— 会破坏 MCP stdio 管道导致超时 / -32000。
codex_web_search(单步搜索)codex_web_research(多步深度研究)适合「打开官网文档、长文里找关键段落、跟随链接深挖」的场景。所有操作可在一次调用里组合,
也可分多轮调用(靠自动维持的会话上下文,用上一轮返回的 ref_id 串联)。来源列表里会带
[turn0search0: 标题 → 域名] 这样的标记,模型在后续 open/find/click 里直接引用 turn0search0 即可。
至少提供
search_query/open/find/click中的一项;四项都空会报错。
web_fetch(抓正文)返回剥离脚本/样式/标签后的纯文本。自动探测 charset 解码 GBK/GB2312 等中文编码,跟随 301/302 重定向,补足「搜到链接却读不到正文、JS 渲染页读不到」的短板。 (注意:纯 JS 动态渲染、需登录的页面仍可能读不到内容,这是服务端 fetch 的能力边界。)
直接用 initialize / tools/list 在终端手动运行 exe 验证握手;或在客户端里用 /mcp 查看是否连上。
排查网络 / 重试问题时,启动 exe 时加 --verbose(或设 CODEX_MCP_LOG=debug),可在 stderr 看到每次请求的 HTTP 状态、耗时与重试过程。
二进制由 GitHub Actions 自动构建(.github/workflows/release.yml):打 tag 即跨平台编译,
并在 GitHub Release 附上 5 个平台的原生二进制(codex-web-search-mcp-<platform>)外加
checksums.txt(SHA-256 清单,供安装脚本/用户校验完整性)。用户走「方式 A/方式 0」下载即用,
无需任何 npm 账号。演进方向见 ROADMAP.md。
git tag v2.3.1 && git push origin v2.3.1
二进制文件名在 CI 里按平台重命名(
win32-x64/darwin-universal等),与上方「方式 A」表格一致。
Model-independent web search & deep research MCP server for Claude Code, powered by OpenAI Codex's standalone search endpoint. Works with any model (Gemini/OpenRouter/local), zero npm dependencies.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Codex Web Search 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 Model-independent web search & deep research MCP server for Claude Code, powered by OpenAI Codex's standalone search endpoint. Works with any model (Gemini/OpenRouter/local), zero npm dependencies.