Skip to main content
Glama
dhicoc

codex-web-search-mcp

by dhicoc
OverviewSchemaRelated ServersScoreDiscussions
Rust
Remote

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（免费，只要 codex login 登录态）；

  • 3 个工具：codex_web_search、codex_web_research、web_fetch；

  • web_fetch 自动探测中文编码（GBK/GB2312 等）、跟随 301/302 重定向，避免乱码与空正文；

  • Codex 请求自动重试：对 429 / 服务端 5xx / 网络抖动做指数退避（最多 3 次：500ms、1s）；401/403 以及其它 4xx（如 400 校验失败）直接友好报错、不重试；

  • Token 自动刷新：收到 401 且本机 auth.json 带有 refresh_token 时，自动换发新 access_token 并回写（先备份），免去手动 codex login；

  • 来源去重 + 按域名聚合：多步 research 返回的来源按 ref_id/url 去重，并按域名分组展示，引用更干净；

  • 可分级日志：--verbose 或 CODEX_MCP_LOG=debug 把请求 URL、HTTP 状态、耗时、重试写到 stderr（绝不污染 MCP 的 stdout 管道）；

  • 独立二进制，无需 Rust 运行时即可运行（下载预编译 exe 即用）。

灵感与端点实现来自 mateusdcc/pi-gpt-search（MIT）。

解决什么问题

Claude Code 原生的 WebSearch / WebFetch 工具绑定 Anthropic API。一旦把基座模型换成 Gemini、OpenRouter、本地模型等非 Anthropic 模型，这些工具就会失灵。

本工具直连 Codex 的独立搜索端点，与底层模型完全无关——无论客户端用哪个模型， 都能通过 MCP 工具获得实时联网搜索能力，且不消耗 GPT/Codex 的推理 token（只占用账号搜索额度，见下）。

Related MCP server: grok-search-mcp

工作原理

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
   │  端点（免费登录态）  │
   └─────────────────────┘

  • Codex 端点不执行 GPT 推理，只返回结构化搜索结果（零 GPT token）。

  • 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。

依赖与环境

  1. 有效的 Codex 登录凭证（必做）——直连 Codex 搜索端点，必须有登录态，否则工具返回清晰报错而非崩溃。 凭证二选一：

    • 方式 1（推荐，零手动配置）：codex login，OAuth 自动把 token 写入 ~/.codex/auth.json；

    • 方式 2（免 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（速率超限）时，重登录或稍后重试即可。

获取 Codex 凭证（必做）

不必手动编写 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 即可使用。三种拿到二进制的方式：

  • 方式 0（最省事，推荐）：一行命令自动安装

    • macOS / Linux：

      curl -fsSL https://raw.githubusercontent.com/dhicoc/codex-web-search-mcp/main/scripts/install.sh | bash

    • Windows（PowerShell）：

      irm https://raw.githubusercontent.com/dhicoc/codex-web-search-mcp/main/scripts/install.ps1 | iex

    脚本会自动识别平台、下载预编译二进制、校验 SHA-256、安装并给出 MCP 配置片段；加 --write-config 可顺手生成 .mcp.json。

  • 方式 A：去 Releases 手动下载预编译文件 —— 下载即用，零依赖。每个 Release 附带 checksums.txt（SHA-256 清单）供校验。各平台文件名见下「配置 MCP · 方式 A」。

  • 方式 B：从源码编译（见下「编译（Build）」），产物直接运行。

编译（Build）

Windows（MSVC）

# 本仓库脚本已注入 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。

macOS / Linux

cargo build --release
# 产物： target/release/codex-web-search-mcp

配置 MCP

方式 A：下载预编译二进制（开箱即用，推荐）

去 Releases 下载与你平台匹配的文件， 放到任意目录即可使用——不需要 Rust、不需要 Node：

平台

文件名

Windows x64

codex-web-search-mcp-win32-x64.exe

Windows ARM64

codex-web-search-mcp-win32-arm64.exe

macOS（Intel / Apple Silicon 通用）

codex-web-search-mcp-darwin-universal

Linux x64

codex-web-search-mcp-linux-x64

Linux ARM64

codex-web-search-mcp-linux-arm64

MCP 配置（把 command 换成你下载的文件路径）：

{
  "mcpServers": {
    "codex-web-search": {
      "command": "C:/path/to/codex-web-search-mcp-win32-x64.exe"
    }
  }
}

  • macOS / Linux：把 command 换成你下载文件的实际路径（如 /path/to/codex-web-search-mcp-darwin-universal）。

  • 改完重启客户端即可；首次在客户端里查看是否连上（如 Claude Code 的 /mcp）。

  • 写入用户级配置（如 ~/.claude.json）的 mcpServers 即对所有项目生效。

方式 B：从源码编译（无预编译 / 想自己构建）

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"
    }
  }
}

  • macOS / Linux：把 command 换成 /path/to/codex-web-search-mcp/target/release/codex-web-search-mcp。

  • 编译步骤见下「编译（Build）」。

  • 改完重启客户端即可；首次在客户端里查看是否连上（如 Claude Code 的 /mcp）。

  • 写入用户级配置（如 ~/.claude.json）的 mcpServers 即对所有项目生效。

可选项：在 MCP 配置的 "env" 里加 CODEX_ACCESS_TOKEN 覆盖凭证（方式 2）。若用 codex login，连 exe 路径都不用配 env。

⚠️ 不要用 "command": "cmd", "args": ["/c", ...] —— 会破坏 MCP stdio 管道导致超时 / -32000。

工具一览

codex_web_search（单步搜索）

参数

类型

说明

query

string（必填）

搜索关键词或问题

recency

number

仅返回最近 N 天内的结果

domains

string[]

限定搜索域名，如 ["github.com"]

response_length

short/medium/long

返回详略程度

codex_web_research（多步深度研究）

适合「打开官网文档、长文里找关键段落、跟随链接深挖」的场景。所有操作可在一次调用里组合， 也可分多轮调用（靠自动维持的会话上下文，用上一轮返回的 ref_id 串联）。来源列表里会带 [turn0search0: 标题 → 域名] 这样的标记，模型在后续 open/find/click 里直接引用 turn0search0 即可。

参数

类型

说明

search_query

{q, recency?, domains?}[]

要执行的搜索查询列表

open

{ref_id, lineno?}[]

按 ref_id 打开文档/页面

find

{ref_id, pattern}[]

在已打开文档中查找关键词

click

{ref_id, id}[]

点击文档内某元素/链接

response_length

short/medium/long

返回详略程度（默认 long）

session_id

string

可选：覆盖/接续会话 id

至少提供 search_query / open / find / click 中的一项；四项都空会报错。

web_fetch（抓正文）

参数

类型

说明

url

string（必填）

要抓取的网址

返回剥离脚本/样式/标签后的纯文本。自动探测 charset 解码 GBK/GB2312 等中文编码，跟随 301/302 重定向，补足「搜到链接却读不到正文、JS 渲染页读不到」的短板。 （注意：纯 JS 动态渲染、需登录的页面仍可能读不到内容，这是服务端 fetch 的能力边界。）

可选环境变量

变量

说明

CODEX_ENDPOINT

覆盖 Codex 搜索端点 URL（默认 https://chatgpt.com/backend-api/codex/alpha/search）。可用于指向反向代理 / 自托管网关，也便于本地联调。

CODEX_REFRESH_ENDPOINT

覆盖刷新 access_token 的端点（默认 https://chatgpt.com/backend-api/auth/refresh）。仅当 auth.json 含 refresh_token 时，在收到 401 时自动调用。Codex 刷新端点未正式公开，若默认地址失效请设此变量指向正确地址。

CODEX_ACCESS_TOKEN / CODEX_ACCOUNT_ID

覆盖登录凭证（方式 2）。

CODEX_MCP_LOG

设为 debug / verbose / 1 开启调试日志（等价于命令行 --verbose）。日志写 stderr，不影响 MCP 通信。

调试与排错

直接用 initialize / tools/list 在终端手动运行 exe 验证握手；或在客户端里用 /mcp 查看是否连上。 排查网络 / 重试问题时，启动 exe 时加 --verbose（或设 CODEX_MCP_LOG=debug），可在 stderr 看到每次请求的 HTTP 状态、耗时与重试过程。

现象

原因 / 解决

未找到 Codex 登录凭证

没登录。运行 codex login 或设置 CODEX_ACCESS_TOKEN

Codex 凭证已过期（HTTP 401/403）

会话过期，重新 codex login

触发 Codex 速率限制（HTTP 429）

稍后重试，或减少调用频率

Windows 编译报 LNK1181: 无法打开输入文件“kernel32.lib”

INCLUDE/LIB 用了正斜杠。用 scripts/build.sh（已处理反斜杠）或手动导出带 C:\ 反斜杠的 VS 环境变量

MCP 显示未连接 / timed out / -32000

检查 exe 路径是否正确、JSON 是否合法；确认没用 cmd /c 包裹命令

想看请求 / 重试细节

启动加 --verbose（或设 CODEX_MCP_LOG=debug），stderr 输出 HTTP 状态、耗时、重试

与原项目的差异

维度

pi-gpt-search（原，TS）

旧版本项目（Node）

本项目 v2.3.1（Rust 重写）

语言

TypeScript

单文件 Node 脚本

Rust

运行依赖

Node + TS

Node

无（独立二进制）

后端

Codex

Codex

Codex

工具数

search/research

2

3（新增 web_fetch）

引用清理

PUA 私有区字符

PUA 私有区字符

重写为可读 [turn0searchN: 标题 → 域名]

发布（维护者）

二进制由 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」表格一致。

Available Tools

2 tools
codex_web_researchA

多步深度研究工具：在 Codex 的联网检索 + 文档浏览引擎上执行「搜索 → 打开文档 → 页内查找 → 点击链接」的迭代研究。所有操作可在一次调用中组合，也可分多轮调用（依靠自动维持的会话上下文，用上一轮返回的 ref_id 串联）。典型流程：先用 search_query 搜索，拿到 ref_id 后用 open(ref_id) 打开权威文档，用 find(ref_id, pattern) 在长文档里定位关键段落，必要时用 click(ref_id, id) 跟随链接。open 返回的文档正文里会内联 [cN: 文本 → 域名] 标记，其中的编号 N 就是可点击元素的 id，直接用于 click({ ref_id, id: N })。返回内容同时含 ref_id 以便后续操作引用。与底层模型无关，适合非 Anthropic 模型下的联网调研。需要有效的 Codex 登录凭证。

ParametersJSON Schema
NameRequiredDescriptionDefault
findNo在已打开文档中查找关键词（可选）。
openNo按 ref_id 打开文档/页面（可选）。
clickNo点击文档内某元素/链接（可选）。
session_idNo可选：覆盖本次研究的会话 id。不传则复用 server 自动维持的会话，从而接续之前搜索得到的 ref_id 上下文。
search_queryNo要执行的搜索查询列表（可选，但至少需提供一项操作）。
response_lengthNo返回内容详略程度（可选，默认 long）。

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so richly. It discloses that operations can be chained using ref_id across calls, that session context is auto-maintained, that open() inlines [cN: text → domain] markers where N is the clickable id, that responses contain ref_id, and that valid Codex login credentials are required. These go far beyond schema details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a dense paragraph, but every sentence earns its place: purpose, workflow, mechanics, and requirements. It is logically organized and front-loaded with the tool's core purpose. Slightly long, but appropriate given the operational complexity it must convey.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-step tool with no output schema, the description covers the workflow and return of ref_id, but does not specify the exact structure of search results or opened document bodies. This is a minor gap; the description is still sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds crucial semantics: it explains the meaning of ref_id as a chaining token, how the click id N is derived from inline markers, and that session_id overrides the auto-maintained session. This makes the parameters actionable beyond their raw names and schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly identifies the tool as a multi-step deep research tool and details the exact operation sequence: '搜索 → 打开文档 → 页内查找 → 点击链接' (search, open, find, click). It names the underlying engine (Codex web retrieval + document browsing) and clearly distinguishes itself from the sibling codex_web_search by emphasizing multi-step research.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a concrete typical workflow (search → open → find → click) and explains that operations can be combined in one call or split across rounds using session context. It mentions suitability for non-Anthropic models, but does not explicitly state when one should choose this tool over codex_web_search or describe exclusions, missing the highest bar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.1.0
    • First observedcodex_web_research
    • First observedcodex_web_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clear, distinct role: one performs a single web search, the other executes iterative multi-step research. Despite both involving search, the workflow difference is explicitly described, making selection unambiguous.

Naming Consistency5/5

Both tool names follow the same pattern: codex_ + web_ + action verb (search/research). The naming is consistent and predictable.

Tool Count3/5

With only two tools, the server feels thin even though the domain is narrow. The two tools cover both quick and deep research, but the count is at the borderline for minimal acceptable scope.

Completeness4/5

The tool set covers single searches and complex research workflows including opening, finding within, and clicking links. Minor gaps exist (e.g., no explicit session management), but the surface is adequate for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • grok-search-mcp

    z2z23n0
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server that enables coding agents to search X/Twitter and the web through the local Grok CLI, providing better search results than default Codex or Claude search without requiring an API key.
    36
    6
    MIT

  • RepoChatMCP

    gzmagyari
    A
    license
    A
    quality
    D
    maintenance
    A zero-dependency MCP server that enables searching and reading local Claude Code and Codex chat sessions, supporting full-text search, grep, and knowledge indexing from chat history.
    15
    14
    MIT

  • Parallel Search MCP

    L-Chris
    F
    license
    A
    quality
    C
    maintenance
    An MCP server that brings Parallel web search and URL extraction to Codex and other Model Context Protocol clients.
    2
    21
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dhicoc/codex-web-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server