@yyaylt/zhipu-web-search-mcp-server

v1.0.8

Published

3 days ago

MCP server for ZHIPU AI Web Search API integration

0High
0Medium
0Low

yyaylt

zhipu web-search mcp-server

zhipu-web-search-mcp-server

基于智谱开放平台 Web Search API 实现的 MCP 服务器，为 Codex、opencode 等 MCP 客户端提供网络搜索能力。

功能特性

支持 4 种搜索引擎：智谱基础版（search_std）、智谱高阶版（search_pro）、搜狗（search_pro_sogou）、夸克搜索（search_pro_quark）
支持搜索意图识别（search_intent）
支持结果条数、域名白名单过滤、时间范围过滤、内容长度控制
返回 Markdown 文本 + 结构化 JSON 数据

环境要求

Node.js >= 18
智谱 API Key：从 https://bigmodel.cn/usercenter/proj-mgmt/apikeys 获取

使用 npx 启动

发布包含此功能的 npm 版本后，无需克隆仓库或手动构建即可启动：

$env:ZHIPU_API_KEY = "your_api_key_here"
npx -y @yyaylt/zhipu-web-search-mcp-server

服务器通过 stdio 与 MCP 客户端通信，启动后等待客户端请求。首次运行需要联网下载 npm 包。

从源码安装与构建

开发和测试使用 Node.js 22 或 24；已发布包的运行要求仍为 Node.js >= 18。

npm install
npm run build

在 Codex 中使用

Codex 通过 stdio 连接本地 MCP 服务器。使用 codex mcp add 添加并传入 API Key：

codex mcp add zhipu-web-search --env ZHIPU_API_KEY=your_api_key_here -- npx -y @yyaylt/zhipu-web-search-mcp-server

Windows 下若客户端无法直接执行 npx，可将启动命令改为 cmd /c npx -y @yyaylt/zhipu-web-search-mcp-server。添加后重启 Codex，即可在会话中调用 zhipu_web_search 工具。

配置

通过环境变量 ZHIPU_API_KEY 提供 API Key：

# PowerShell
$env:ZHIPU_API_KEY = "your_api_key_here"

在 opencode 中使用

在 opencode.json 中添加 MCP 服务器配置：

{
  "mcp": {
    "zhipu-web-search": {
      "type": "local",
      "command": ["npx", "-y", "@yyaylt/zhipu-web-search-mcp-server"],
      "environment": {
        "ZHIPU_API_KEY": "your_api_key_here"
      }
    }
  }
}

或使用 opencode mcp add 命令添加：

opencode mcp add zhipu-web-search -- npx -y @yyaylt/zhipu-web-search-mcp-server

然后设置环境变量后重启 opencode 即可。

若 Windows 客户端无法直接执行 npx，可将 command 改为 ["cmd", "/c", "npx", "-y", "@yyaylt/zhipu-web-search-mcp-server"]。使用本地源码时，仍可将 command 设置为 ["node", "D:\\path\\to\\zhipu-web-search-mcp-server\\dist\\index.js"]。

可用工具

zhipu_web_search

执行网络搜索，返回网页标题、摘要、链接、网站名称等信息。

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | search_query | string | 必填 | 搜索内容，不超过 70 字符 | | search_engine | string | search_std | 搜索引擎：search_std / search_pro / search_pro_sogou / search_pro_quark | | search_intent | boolean | false | 是否执行搜索意图识别 | | count | number | 支持的引擎默认 10 | search_std / search_pro：1-50 的整数；search_pro_sogou：仅 10/20/30/40/50；search_pro_quark：不支持，不能指定 | | search_domain_filter | string | - | 白名单域名过滤（search_std / search_pro / search_pro_sogou 支持） | | search_recency_filter | string | noLimit | 时间过滤：oneDay / oneWeek / oneMonth / oneYear / noLimit | | content_size | string | medium | 内容长短：medium / high | | user_id | string | - | 终端用户 ID，6-128 字符 |

条数行为依据 Web Search API 官方参数文档：

count 是请求条数，输出 JSON 的 count 是实际收到的 results.length，不能将两者视为必然相等。
官网在搜狗枚举说明后注明同时指定 search_domain_filter 和 search_recency_filter 时 count 不生效，未明确此备注对其他引擎的适用范围。项目保留用户的具体过滤条件并提示此限制。
search_recency_filter 为 noLimit 时省略该请求字段，避免默认值导致同时携带域名和时间过滤；官网未明确服务端是否将显式 noLimit 计入上述限制。
夸克不发送 count；显式指定会返回参数错误。搜狗的非法条数也会在发送请求前拒绝。
夸克不支持 search_domain_filter，显式指定会返回参数错误；纯空白搜索词也会被拒绝。
最终 Markdown（含意图、标题和提示）最多 100,000 字符，按完整条目截断；超长意图最多使用四分之一文本预算。截断标题显示“展示 X 条，共 Y 条”，结构化结果保留完整列表。
HTTP 响应体限制为 8 MiB，超过时返回错误；无效响应不会被当作空结果。客户端取消请求会中止 HTTP 请求，不自动重试。

隐私与安全提示

ZHIPU_API_KEY 仅通过环境变量注入，请勿将其写入代码、配置仓库或提交到 Git 历史。
user_id 参数会原样透传给智谱开放平台，请仅传入匿名化/不可逆的终端用户标识，切勿传入邮箱、手机号、身份证号等真实个人身份信息。
搜索内容（search_query）会发送至智谱开放平台进行检索，请避免在搜索词中包含个人敏感信息。
服务器不主动存储搜索历史；错误日志仅记录固定分类，不记录 API Key、请求体或原始异常。MCP 客户端可能自行保存通信内容或 stderr，请根据客户端配置管理日志。

错误码说明

| 错误码 | 含义 | 处理建议 | |--------|------|----------| | 1701 | 网络搜索并发已达上限 | 稍后重试或减少并发请求 | | 1702 | 系统未找到可用的搜索引擎服务 | 检查配置或联系管理员 | | 1703 | 搜索引擎未返回有效数据 | 调整查询条件 |

开发

npm run dev    # tsx watch 模式开发
npm run build  # 编译到 dist/
npm pack       # 自动构建并生成包含可执行入口的 npm 包
npm run typecheck # 检查源码和测试的 TypeScript 类型
npm test          # 自动构建并执行回归测试
npm run test:package # 临时安装真实 npm 包，验证 bin 启动和 MCP 握手（需要联网）

验证

构建成功后启动服务器，若未设置 ZHIPU_API_KEY 会提示缺失：

node dist/index.js
# ERROR: ZHIPU_API_KEY 环境变量是必需的

License & Acknowledgments

This project is licensed under the MIT License. See LICENSE for details.

Contributions are welcome — please read CONTRIBUTING.md before submitting code.

It includes third-party packages with the following licenses (historical snapshot; manually refresh via npx license-checker --summary; counts may vary with dependency versions):

MIT (95 packages)
BlueOak-1.0.0 (7 packages)
ISC (7 packages)
Apache-2.0 (1 package)
BSD-3-Clause (2 packages)
BSD-2-Clause (1 package)

提示：以上数量为生成本文档时的快照。依赖升级后可用 npx license-checker --summary 重新生成核对。