search-mcp-worker

Search without limits. Pay nothing. 搜索无边界，免费自托管。

A self-hosted MCP search aggregation service on Cloudflare Workers. 24 search/fetch tools via JSON-RPC 2.0. Free. Self-hosted. Chinese-first.

⚡ 30 秒接入（无需部署）

本项目提供了一个公开的 MCP 端点，你可以直接将其接入你的 AI 客户端，无需自己部署任何东西：

https://search-mcp-worker.sean010629.workers.dev/mcp

Claude Desktop / Cursor / Windsurf / VS Code

在你的 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "search": {
      "url": "https://search-mcp-worker.sean010629.workers.dev/mcp"
    }
  }
}

Hermes Agent

hermes mcp add search --url "https://search-mcp-worker.sean010629.workers.dev/mcp"

其他 MCP 客户端

任何支持 Streamable HTTP transport 的 MCP 客户端均可接入，将 MCP server URL 设为：

https://search-mcp-worker.sean010629.workers.dev/mcp

curl 测试

# 初始化连接
curl -X POST https://search-mcp-worker.sean010629.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# 智能搜索（自动检测语言和意图）
curl -X POST https://search-mcp-worker.sean010629.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search","arguments":{"query":"Rust async runtime","limit":3}}}'

公开实例说明： 免费搜索引擎（DuckDuckGo/Bing/Baidu/arXiv/GitHub 等 19 个）均可直接使用。Bocha 引擎需要 API Key，公开实例已内置，但额度有限。如果你需要更高的 Bocha 配额或有数据隐私顾虑，建议自行部署。

功能概览

智能路由

search 工具会自动分析查询内容：

"Rust 异步运行时对比"    → 中文 + 开发者意图 → Bocha → GitHub → StackExchange → 百度
"transformer attention"  → 英文 + 学术意图   → arXiv → PubMed → CrossRef → DuckDuckGo
"今天北京天气"           → 中文 + 新闻意图   → Bocha → 百度 → Bing CN
"what is MCP"            → 英文 + 参考意图   → Wikipedia → DDG Instant Answer → DuckDuckGo

结果质量处理

• 去重：跨引擎 URL 标准化合并
• 评分：质量权重 + 排名衰减 + 多源加成 + Token 匹配 + 官方域名加成
• 过滤：通用噪音检测、意图不匹配检测、低信任域名检测
• 缓存：5 分钟 LRU 缓存（200 条）

24 个 MCP 工具

智能搜索

通用搜索

中文搜索

学术搜索

开发者搜索

参考工具

内容获取

快速开始（自托管）

如果你只想使用本服务，无需阅读以下内容——直接看上面的 ⚡ 30 秒接入 即可。以下内容面向想要自己部署的用户。

前置条件

• Node.js >= 22
• Wrangler CLI (npm install -g wrangler)
• Cloudflare 账号（免费计划即可）

1. 克隆项目

git clone https://github.com/Xuan0629/search-mcp-worker.git
cd search-mcp-worker

2. 安装依赖

npm install

注意： Node 24 + npm 11 存在已知的不解包 bug。如果 npm install 后 node_modules 为空，请使用 Node 22 LTS，或手动解包：

cd /tmp && npm pack typescript hono @cloudflare/workers-types
cd /path/to/search-mcp-worker
mkdir -p node_modules/typescript node_modules/hono node_modules/@cloudflare/workers-types
tar xzf /tmp/typescript-*.tgz -C node_modules/typescript --strip-components=1
tar xzf /tmp/hono-*.tgz -C node_modules/hono --strip-components=1
tar xzf /tmp/cloudflare-workers-types-*.tgz -C node_modules/@cloudflare/workers-types --strip-components=1

3. 登录 Cloudflare

wrangler login

4. 配置 Bocha API Key（可选但推荐）

Bocha 提供高质量的中文/英文搜索 API，是中文查询的主力引擎。

wrangler secret put BOCHA_API_KEY
# 输入你的 Bocha API Key

不配置 Bocha 也可以使用，智能路由会自动跳过 Bocha，使用其他免费引擎。

5. 本地开发

npm run dev
# Worker 运行在 http://localhost:8789

6. 部署

npm run deploy

部署后会得到一个 *.workers.dev 域名，例如：

https://search-mcp-worker.<your-subdomain>.workers.dev

MCP 协议

端点

POST https://search-mcp-worker.<your-subdomain>.workers.dev/mcp
Content-Type: application/json

协议版本

• MCP: 2025-03-26
• JSON-RPC: 2.0

支持的方法

示例：初始化

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "search-mcp-worker", "version": "0.1.0" }
  }
}

示例：智能搜索

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "Rust 异步运行时对比",
      "limit": 5,
      "auto_mode": "quick"
    }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "## Search Results\n\nQuery: \"Rust 异步运行时对比\" | Intent: developer | Lang: zh | Engines: bocha, github, stackexchange\n\n1. **Tokio** ..."
    }],
    "structuredContent": { "results": [...], "query": "...", "engines": [...], "cached": false }
  }
}

示例：获取网页内容

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "fetch_url",
    "arguments": {
      "url": "https://example.com",
      "maxChars": 5000
    }
  }
}

接入 MCP 客户端（自托管实例）

公开实例的接入方式见上方 ⚡ 30 秒接入。以下为你自己部署后的接入方式——将 URL 替换为你的 *.workers.dev 域名。

Claude Desktop / Cursor / Windsurf

在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "search": {
      "url": "https://search-mcp-worker.<your-subdomain>.workers.dev/mcp"
    }
  }
}

Hermes Agent

hermes mcp add search --url "https://search-mcp-worker.<your-subdomain>.workers.dev/mcp"

或手动添加到 ~/.hermes/config.yaml：

mcp_servers:
  search:
    url: "https://search-mcp-worker.<your-subdomain>.workers.dev/mcp"
    timeout: 120

OpenClaw / 其他支持 MCP 的客户端

任何支持 Streamable HTTP transport 的 MCP 客户端均可接入，将 URL 指向：

https://search-mcp-worker.<your-subdomain>.workers.dev/mcp

工具参数说明

通用搜索参数

所有搜索工具共享以下基础参数：

search（智能搜索）额外参数

特定工具参数

架构

src/
├── index.ts              # 入口：Hono app、路由、工具注册
├── types.ts              # TypeScript 类型定义
├── constants.ts          # 常量：引擎注册表、评分权重、UA 池
├── cache.ts              # LRU 缓存
├── router.ts             # 智能路由：语言检测 + 意图分类 + 引擎选择
├── scorer.ts             # 结果处理：去重 + 质量评估 + 评分 + 排序
├── mcp/
│   └── protocol.ts       # MCP 协议层：JSON-RPC 处理 + 工具 schema
└── engines/
    ├── bocha.ts          # Bocha API（web-search + ai-search）
    ├── duckduckgo.ts     # DuckDuckGo（3 条 fallback 路径）
    ├── bing.ts           # Bing + Bing CN
    ├── baidu.ts          # 百度（JSON API + HTML fallback）
    ├── sogou.ts          # 搜狗
    ├── google.ts         # Google（占位，高频 CAPTCHA）
    ├── academic.ts       # arXiv + PubMed + CrossRef
    ├── developer.ts      # GitHub + StackExchange + npm + PyPI + crates.io + HN
    ├── reference.ts      # Wikipedia + Wikidata + DDG Instant Answer
    └── fetch.ts          # fetch_url + fetch_github_file + find_rss

智能路由流程

用户查询
  │
  ├─ 语言检测（CJK 字符 → zh，否则 → en）
  ├─ 意图分类（关键词匹配：academic/developer/news/reference/general）
  │
  └─ 路由表查找 → 引擎优先级列表
       │
       ├─ quick 模式：依次尝试，首个成功即返回
       └─ full 模式：尝试所有引擎，合并去重排序后返回

搜索源费用

环境变量

设置方式：

# 生产环境（Cloudflare Workers Secrets）
wrangler secret put BOCHA_API_KEY

# 本地开发（.dev.vars 文件）
echo "BOCHA_API_KEY=your-key-here" > .dev.vars

自定义

修改路由优先级

编辑 src/router.ts 中的 ROUTING_TABLE：

const ROUTING_TABLE: Record<Intent, Record<Language, string[]>> = {
  general: {
    zh: ['bocha', 'baidu', 'bing_cn', 'sogou', 'duckduckgo', 'bing'],
    en: ['duckduckgo', 'bing', 'bocha', 'google'],
    // ...
  },
  // ...
};

添加新搜索引擎

1. 在 src/engines/ 下创建新文件，实现搜索函数：

import type { SearchResult } from '../types';
import { DEFAULT_TIMEOUT_MS } from '../constants';

export async function searchMyEngine(
  query: string, limit: number, timeout = DEFAULT_TIMEOUT_MS,
): Promise<SearchResult[]> {
  // 实现搜索逻辑
  return results;
}

2. 在 src/constants.ts 的 ENGINE_REGISTRY 中注册
3. 在 src/mcp/protocol.ts 的 getToolList() 中添加工具定义
4. 在 src/index.ts 的 executeEngine() 和 toolHandlers 中添加调度

绑定自定义域名

在 wrangler.toml 中添加：

[[routes]]
pattern = "search.yourdomain.com/*"
zone_name = "yourdomain.com"

开发命令

npm run dev          # 本地开发服务器 (http://localhost:8789)
npm run deploy       # 部署到 Cloudflare Workers
npm run typecheck    # TypeScript 类型检查
npm run test         # 运行测试

致谢

灵感来源于 Kerry1020/search-mcp-worker。本项目从零重写，聚焦于：

• TypeScript 类型安全
• 模块化架构（每引擎一个文件）
• 智能路由系统（语言 + 意图自动检测）
• 可维护性和可扩展性

License

MIT