🌐 Web Search MCP

🔍 多引擎 AI 联网搜索 MCP 服务 — 一站式接入，随心切换

✨ 功能特性

特性	说明
🔌 多引擎支持	Kimi · 智谱 · 火山引擎 · 腾讯云 · 阿里云，一个服务全搞定
🎯 动态工具发现	按需传参，只暴露你配置了的搜索引擎
🔀 默认搜索别名	`default-search=kimi` 即可生成通用 `web-search` 工具
📡 MCP 协议	完整实现 Model Context Protocol (2026-07-28)
⚡ 零运行时依赖	全部使用原生 `fetch`，无第三方依赖
🚀 轻量高效	基于 Bun 运行时，启动快、内存占用低
📦 npm 可复用	可导入服务器、注册表或任意 Provider，也可作为 CLI 启动
🐳 Docker 支持	开箱即用的 Dockerfile，便于容器化部署
🧩 易于扩展	实现接口 + 注册一行代码 = 新增搜索引擎

🔍 搜索引擎

Provider	Tool 名称	必需参数	说明
🌙 Kimi	`kimi-search`	`kimi-apiKey`	月之暗面 Moonshot AI 联网搜索
🧠 智谱 (Zai)	`zai-search`	`zai-apiKey`	智谱 BigModel 搜索 API，支持多搜索引擎
🌋 火山引擎 (Volces)	`volces-search`	`volces-apiKey`	豆包大模型联网搜索，支持抖音/头条等源
☁️ 腾讯云 (Tencentmaas)	`tencentmaas-search`	`tencentmaas-apiKey`	混元大模型联网搜索
🟠 阿里云 (Aliyuncs)	`aliyuncs-search`	`aliyuncs-apiKey` + `aliyuncs-baseUrl`	通义千问联网搜索（需提供业务空间 URL）

Tip

阿里云需要同时提供 aliyuncs-apiKey 和 aliyuncs-baseUrl（如 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com）才会在 tools/list 中显示。

🚀 快速开始

📋 环境要求

Bun >= 1.0.0
至少一个搜索引擎的 API Key

📦 安装依赖

bun install

🏃 开发运行

bun run dev

服务启动后即可使用：

🚀 MCP Server running at http://localhost:3000
🔑 Example: POST http://localhost:3000/mcp?kimi-apiKey=YOUR_KEY
📚 Supported providers: kimi, zai, volces, tencentmaas, aliyuncs

🔨 构建可执行文件

bun run build:binary

编译后的可执行文件位于 dist/web-search-mcp。如果要构建 npm 包，运行 bun run build。

📦 作为 npm 包使用

项目需要 Bun 运行时（>= 1.1）。安装后可以直接使用 CLI：

npm install web-search-mcp
npx web-search-mcp

也可以显式导入服务器并自行配置端口、路径或 Provider 注册表。导入模块不会自动监听端口：

import { createDefaultRegistry, startServer } from "web-search-mcp";

const server = startServer({
  port: 3000,
  registry: createDefaultRegistry(),
});

console.log(`MCP server: ${server.url}/mcp`);

只需要服务器模块时，可以使用 web-search-mcp/server：

import { startServer } from "web-search-mcp/server";

const server = startServer({ port: 3000 });

🔌 stdio 模式

全局安装后，可以通过 MCP 标准输入输出传输启动服务。stdout 只输出 JSON-RPC 消息，日志会写入 stderr：

npm install --global @herta-ai/web-search-mcp
# 或：bun install --global @herta-ai/web-search-mcp
web-search-mcp --stdio

也可以直接使用专用命令 web-search-mcp-stdio，或者在未全局安装时运行：

npx -y @herta-ai/web-search-mcp --stdio

stdio 没有 HTTP URL 参数，Provider 配置通过环境变量传入。例如：

{
  "mcpServers": {
    "web-search": {
      "command": "web-search-mcp",
      "args": ["--stdio"],
      "env": {
        "KIMI_API_KEY": "YOUR_KEY",
        "DEFAULT_SEARCH": "kimi"
      }
    }
  }
}

Provider 参数会把现有的 {provider}-{parameter} 名称转换为大写下划线形式，例如 kimi-apiKey 对应 KIMI_API_KEY，aliyuncs-baseUrl 对应 ALIYUNCS_BASE_URL。也支持加上 MCP_ 或 WEB_SEARCH_MCP_ 前缀。

在代码中也可以从 @herta-ai/web-search-mcp/stdio 导入 startStdioServer 或 runStdioServer。

Provider 也可以单独导入使用。每个 Provider 接收搜索词和 URL 参数，因此可以嵌入自己的服务或任务：

import { KimiProvider } from "web-search-mcp/providers/kimi";

const kimi = new KimiProvider();
const result = await kimi.search(
  "今天北京天气",
  new URLSearchParams({ "kimi-apiKey": process.env.KIMI_API_KEY! }),
);

根入口也导出了 KimiProvider、ZaiProvider、VolcesProvider、TencentmaasProvider、AliyuncsProvider、ProviderRegistry 和 startServer。

🔐 npm OIDC 发布

仓库中的 .github/workflows/npm-publish.yml 使用 npm trusted publishing，通过 GitHub Actions 的 OIDC 身份发布并生成 provenance。首次发布前，请在 npm 包设置中把 GitHub 仓库、工作流文件名 npm-publish.yml 和发布分支配置为 trusted publisher，然后创建一个 GitHub Release：

git tag v0.1.0
git push origin v0.1.0

发布工作流会执行类型检查、构建和 npm pack --dry-run，随后运行 npm publish --provenance，无需保存 npm token。

⚙️ 配置参数

所有参数均通过 URL Query String 传递，格式为 {provider}-{param}。

🌙 Kimi

参数	必填	默认值	说明
`kimi-apiKey`	✅	—	Moonshot API Key
`kimi-model`	—	`moonshot-v1-32k`	模型名称

🧠 智谱 (Zai)

参数	必填	默认值	说明
`zai-apiKey`	✅	—	智谱 API Key
`zai-search_engine`	—	`search_std`	搜索引擎 (`search_std` / `search_pro` / `search_pro_sogou` / `search_pro_quark`)
`zai-count`	—	`10`	返回结果数 (1-50)
`zai-search_recency_filter`	—	`noLimit`	时间过滤 (`oneDay` / `oneWeek` / `oneMonth` / `oneYear` / `noLimit`)
`zai-content_size`	—	`medium`	内容长度 (`medium` / `high`)

🌋 火山引擎 (Volces)

参数	必填	默认值	说明
`volces-apiKey`	✅	—	火山引擎 API Key
`volces-model`	—	`doubao-seed-2-0-mini-260428`	模型名称
`volces-max_keyword`	—	`2`	最大关键词数 (1-50)
`volces-limit`	—	`10`	最大返回结果数 (1-50)
`volces-sources`	—	—	附加搜索源，逗号分隔 (`douyin,moji,toutiao`)

☁️ 腾讯云 (Tencentmaas)

参数	必填	默认值	说明
`tencentmaas-apiKey`	✅	—	腾讯云 API Key
`tencentmaas-model`	—	`hy3`	模型名称
`tencentmaas-search_source`	—	`standard`	搜索版本 (`lite` / `standard`)

🟠 阿里云 (Aliyuncs)

参数	必填	默认值	说明
`aliyuncs-apiKey`	✅	—	阿里云 API Key
`aliyuncs-baseUrl`	✅	—	业务空间 URL（如 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`）
`aliyuncs-model`	—	`qwen3.7-flash`	模型名称

🔀 默认搜索

参数	说明
`default-search`	设为 Provider 名称（如 `kimi`），会额外暴露一个 `web-search` 通用工具，调用时委托给指定 Provider

📡 API 接口

端点

POST http://localhost:3000/mcp?{参数}

💡 使用示例

🔹 只用 Kimi 搜索

POST /mcp?kimi-apiKey=sk-xxxxxxxx

tools/list 返回：kimi-search

🔹 多引擎 + 默认搜索

POST /mcp?kimi-apiKey=sk-xxx&zai-apiKey=zzz&default-search=kimi

tools/list 返回：kimi-search、zai-search、web-search

调用 web-search 等同于调用 kimi-search

🔹 火山引擎自定义参数

POST /mcp?volces-apiKey=sk-xxx&volces-max_keyword=5&volces-sources=douyin,toutiao

tools/list 返回：volces-search

🔹 阿里云（需要 baseUrl）

POST /mcp?aliyuncs-apiKey=sk-xxx&aliyuncs-baseUrl=https://workspace.cn-beijing.maas.aliyuncs.com

tools/list 返回：aliyuncs-search

🔹 全部引擎拉满

POST /mcp?kimi-apiKey=sk-a&zai-apiKey=sk-b&volces-apiKey=sk-c&tencentmaas-apiKey=sk-d&aliyuncs-apiKey=sk-e&aliyuncs-baseUrl=https://ws.maas.aliyuncs.com&default-search=zai

tools/list 返回：kimi-search、zai-search、volces-search、tencentmaas-search、aliyuncs-search、web-search

📨 请求 & 响应示例

获取工具列表：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

调用搜索工具：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "kimi-search",
    "arguments": {
      "query": "今天北京天气怎么样"
    }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "搜索结果..."
      }
    ]
  }
}

🖥️ 在客户端中使用

Claude Desktop

在 Claude Desktop 配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "web-search": {
      "url": "http://localhost:3000/mcp?kimi-apiKey=YOUR_API_KEY&default-search=kimi"
    }
  }
}

Cursor

在 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "web-search": {
      "url": "http://localhost:3000/mcp?kimi-apiKey=YOUR_API_KEY&default-search=kimi"
    }
  }
}

🐳 部署

Docker 构建

docker build -t web-search-mcp .

Docker 运行

docker run -d -p 3000:3000 web-search-mcp

Docker Compose

version: '3'
services:
  web-search-mcp:
    build: .
    ports:
      - "3000:3000"

📁 项目结构

web-search-mcp/
├── src/
│   ├── index.ts              # 📦 npm 库入口（无启动副作用）
│   ├── cli.ts                # 🚪 CLI / Docker 启动入口
│   ├── server.ts             # 🌐 MCP HTTP 服务器（动态路由）
│   ├── stdio.ts              # 🔌 MCP stdio 传输
│   ├── stdio-cli.ts          # 🚪 stdio CLI 启动入口
│   ├── types.ts              # 📝 公共类型定义
│   ├── registry.ts           # 📦 Provider 注册表 & 别名处理
│   └── providers/            # 🔌 搜索引擎 Provider 目录
│       ├── base.ts           #   ├─ 接口定义 & 抽象基类
│       ├── kimi.ts           #   ├─ 🌙 Kimi (Moonshot)
│       ├── zai.ts            #   ├─ 🧠 智谱 (BigModel)
│       ├── volces.ts         #   ├─ 🌋 火山引擎 (豆包)
│       ├── tencentmaas.ts    #   ├─ ☁️ 腾讯云 (混元)
│       └── aliyuncs.ts       #   └─ 🟠 阿里云 (通义千问)
├── dist/                     # 📦 编译输出
├── Dockerfile                # 🐳 Docker 构建文件
├── package.json              # ⚙️ 项目配置
└── tsconfig.json             # 🔧 TypeScript 配置

🧩 扩展新引擎

只需 3 步 即可新增一个搜索引擎：

① 创建 Provider 文件 src/providers/my-engine.ts

import { BaseSearchProvider } from "./base";
import type { WebSearchResult } from "../types";

export class MyEngineProvider extends BaseSearchProvider {
  readonly name = "myengine";
  readonly toolName = "myengine-search";
  readonly description = "我的自定义搜索引擎";
  readonly requiredParams = ["myengine-apiKey"];
  readonly optionalParams = [];

  async search(query: string, urlParams: URLSearchParams): Promise<WebSearchResult> {
    const apiKey = urlParams.get("myengine-apiKey")!;
    // ... 调用搜索 API ...
    return { content: [{ type: "text", text: "搜索结果" }] };
  }
}

② 在注册表中注册 src/registry.ts

import { MyEngineProvider } from "./providers/my-engine";

registry.register(new MyEngineProvider());

③ 完成！ 传入 myengine-apiKey=xxx 即可使用 ✅

🛠️ 技术栈

技术	用途
Bun	⚡ 高性能 JavaScript 运行时
TypeScript	🔒 类型安全
MCP Protocol	📡 Model Context Protocol (2026-07-28)

零运行时依赖 — 所有 HTTP 请求均使用原生 fetch API

📄 许可证

MIT License

Made with ❤️ using Bun — 🌐 搜索无界，引擎随心

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmignore		.npmignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation