What can you do with this server?

The DeepSearch MCP server provides advanced web search capabilities through the Model Context Protocol, delivering higher-quality results than standard AI agent searches with a trade-off of longer response times. Core Tools: * deepsearch: Perform broad web searches returning structured results (title, snippet, URL, relevance score) * deepsearch-web: Execute targeted searches requiring filters for site-specific or time-constrained queries Key Features: * Configure result quantity (1-10) via top_k parameter * Apply filters for domain-specific searches and time range constraints * Specify locale preferences for region-specific results * Access token usage metrics (input/output counts) for each query * Receive consistently structured output with relevance scoring * Integrate seamlessly with MCP clients like Codex, Claude Desktop, and custom TypeScript applications via STDIO protocol

How do I use DeepSearch MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DeepSearch MCP find recent articles about AI advancements in healthcare" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

DeepSearch MCP 项目

DeepSearch MCP 采用 TypeScript 实现，提供统一的客户端、代理层与 MCP 服务器入口，方便在 Model Context Protocol (MCP) 生态中调用可联网的 Deepsearch 模型，实现广域检索与站点定向检索能力。项目通过 Vitest 驱动的 TDD 保证核心逻辑的可测试性。

用户须知

全局安装

npm install -g @yuemingruoan/deepsearch-mcp

安装完成后，可直接执行 deepsearch 命令。运行前请在终端环境中配置 API_KEY、BASE_URL、MODEL_NAME、DEEPSEARCH_TIMEOUT 等变量（可写入 .env 或 shell 配置）。

该项目以https://yunwu.ai为提供商开发，理论上可用于所有one API镜像站，推荐您使用https://yunwu.ai作为您的AI服务提供商，享全网最低价的GPT5-Codex和其他服务。您可前往https://yunwu.ai/register?aff=yzyI注册账号

集成到 Codex 客户端

在 ~/.codex/config.toml 中新增 STDIO 类型服务器，让 Codex 自动启动 DeepSearch MCP：

[mcp_servers.deepsearch] command = "node" args = ["/absolute/path/to/DeepSearch-MCP/bin/deepsearch.js"] env = { "API_KEY" = "<你的 Deepsearch API Key>", "BASE_URL" = "https://yunwu.ai/v1/chat/completions", "MODEL_NAME" = "gemini-2.5-flash-deepsearch", "DEEPSEARCH_TIMEOUT" = "400" } startup_timeout_sec = 30 tool_timeout_sec = 120

常用命令行：

codex mcp list codex mcp get deepsearch codex mcp remove deepsearch

AI须知

⚠️ 在继续之前，请先阅读 codex/AGENTS.md 与 codex/checkpoint.md 获取历史决策与协作规范。

功能特性

deepsearch_mcp/：导出 DeepSearchMCPClient 类型及搜索结果模型，负责与传输层交互并归一化响应。
deepsearch_agents/：包含 DeepSearchAgent 与 DeepSearchWebAgent，分别处理通用检索与站点定向检索场景。
source/api.ts：封装 DeepSearch HTTP 传输层，支持环境变量配置、超时控制与错误处理。
main.ts：MCP 服务器入口，通过 STDIO 暴露 deepsearch 与 deepsearch-web 工具，可直接被 Codex、Claude Desktop 等 MCP 客户端调用。
tests/：基于 Vitest 的单元测试，覆盖客户端、传输层、代理层与服务器工具注册流程。

快速开始

安装依赖（Node.js ≥ 18）：
npm install
配置 .env（示例）：
API_KEY=sk-xxxxxx BASE_URL=https://yunwu.ai/v1/chat/completions MODEL_NAME=gemini-2.5-flash-deepsearch # 可选：覆盖默认超时（秒） DEEPSEARCH_TIMEOUT=400
启动 MCP 服务器（STDIO）：
# 开发模式（依赖 tsx） npm run deepsearch
生产环境或打包后，可执行：
npm run build node dist/main.js
运行测试：
npm test

使用示例（TypeScript）

import { DeepSearchAgent } from "deepsearch-mcp/deepsearch_agents/deepsearch"; const agent = new DeepSearchAgent(); const result = await agent.search("OpenAI 最新发布", { top_k: 3 }); for (const item of result.items) { console.log(item.title, item.url); } agent.close();

站点定向检索可使用 DeepSearchWebAgent 并传入 filters: { site: "example.com" } 或 time_range 等参数；通过 MCP 工具调用时同样使用这些字段。

Node.js 启动脚本

bin/deepsearch.js 会优先执行构建产物 dist/main.js；若未构建，则回退到本地 tsx main.ts。脚本继承当前终端环境变量，因此在 MCP 配置中设置的 API_KEY、BASE_URL 等会自动生效。通过 npm install -g @yuemingruoan/deepsearch-mcp 安装后，系统中的 deepsearch 命令即指向该脚本。

npm run deepsearch -- --top_k 3 # 或者直接调用脚本 node ./bin/deepsearch.js # 全局安装后可直接调用 deepsearch --top_k 3

命令行参数会透传给 main.ts（当前主程序未解析额外参数，通常无需传入）。

发布流程

npm run build：输出 dist/ 目录供分发或发布。
npm publish：依赖 prepublishOnly 钩子自动构建。
.github/workflows/publish.yml：在 GitHub Release 发布时自动运行测试并上传至 npm，需要在仓库中配置 NPM_TOKEN secrets。