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):
- 后端 (免费,只要 登录态);
Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
一个模型无关的 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.
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Codex Web Search läuft lokal über stdio.
Zuletzt geprüft: 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.