快速开始

三步就能跑起来：确认本机有 Node ≥ 18、把服务器写进客户端的 mcpServers、然后让模型做一次搜索验证。 全程不需要 API Key。

前置要求

  • Node.js≥ 18（可用 node -v 检查）
  • 网络能访问搜索引擎。中国大陆建议设置 SEARCH_REGION=cn-zh
  • 客户端任何支持 MCP 的宿主：Claude Desktop / Cursor / Cline / VS Code / 自研 Agent

第 1 步 · 确认服务器可运行

先用 npx 直接拉起来。它会以 stdio 方式启动并等待 JSON-RPC 输入 —— 打印 ready 一行就说明配置正常（日志走 stderr）。

npx -y ai-search-mcp

# 期望在 stderr 看到：
# [ai-search-mcp] [info] ready (version 0.4.1, engine=auto, region=auto, logLevel=info)
这个进程本身不会退出，它正等待标准输入。按 Ctrl + C 结束即可 —— 平时由客户端自动拉起，无需手动运行。

第 2 步 · 写入客户端配置

所有主流客户端都接受同一份结构：{ "mcpServers": { ... } }。把下面片段合并进你已有的配置文件（不要整体覆盖）。

{
  "mcpServers": {
    "ai-search-mcp": {
      "command": "npx",
      "args": ["-y", "ai-search-mcp"],
      "env": {
        "SEARCH_REGION": "cn-zh"
      }
    }
  }
}

各客户端配置文件位置

  • Claude Desktopclaude_desktop_config.json（macOS 在 ~/Library/Application Support/Claude/，Windows 在 %APPDATA%\Claude\）
  • Cursor项目内 .cursor/mcp.json，或全局 ~/.cursor/mcp.json
  • Cline / VS Code客户端的 MCP Servers 面板，或对应扩展的 settings JSON
  • 自研 Agent直接用 @modelcontextprotocol/sdk 的 stdio transport 拉起本进程

变体：接入付费引擎

想让质量更高的官方 API 优先、免费引擎兜底，就给出显式引擎链。缺少 Key 的引擎会在启动时被跳过并打印警告，不会导致启动失败。

{
  "mcpServers": {
    "ai-search-mcp": {
      "command": "npx",
      "args": ["-y", "ai-search-mcp"],
      "env": {
        "SEARCH_ENGINE": "brave,tavily,bing",
        "BRAVE_API_KEY": "your-brave-key",
        "TAVILY_API_KEY": "your-tavily-key",
        "SEARCH_REGION": "cn-zh"
      }
    }
  }
}

变体：从源码运行

本地调试或想改代码时，直接指向 index.js 的绝对路径。Windows 下的路径用正斜杠或双反斜杠均可。

{
  "mcpServers": {
    "ai-search-mcp": {
      "command": "node",
      "args": ["C:/path/to/ai-search-mcp/index.js"],
      "env": {
        "SEARCH_REGION": "cn-zh",
        "SEARCH_LOG_LEVEL": "debug"
      }
    }
  }
}

变体：Docker 运行

镜像基于 node:18-alpine，只装运行时依赖，并以 node index.js 作为入口。stdio 服务无需暴露端口，但必须带 -i 保持标准输入打开。

# 构建
docker build -t ai-search-mcp:latest .

# 手动试跑（交互式 stdin/stdout）
docker run -i --rm --name ai-search-mcp ai-search-mcp:latest
{
  "mcpServers": {
    "ai-search-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--name", "ai-search-mcp", "ai-search-mcp:latest"],
      "env": { "SEARCH_REGION": "cn-zh" }
    }
  }
}
远程部署说明 本服务器使用 stdio 传输，设计上由客户端在本机拉起。要暴露成远程服务，需要自行加一层 SSE 或 Streamable HTTP transport。

第 3 步 · 验证

重启客户端，让它调用一次 search。返回同时出现 engine 与非空 results 即接入成功。

{
  "query": "Model Context Protocol specification",
  "maxResults": 5
}

如果失败，先调用 status（无参数）看是哪个环节出了问题：

{
  "server": "ai-search-mcp",
  "uptimeSec": 812,
  "config": { "engine": "auto", "region": "cn-zh", "ratePerMinute": 8, "cacheTtlMs": 600000 },
  "cache": { "size": 3, "hits": 0, "misses": 3 },
  "engines": [
    { "engine": "bing", "status": "healthy", "lastCode": null, "consecutiveFailures": 0 },
    { "engine": "so360", "status": "untested", "lastCode": null, "consecutiveFailures": 0 }
  ]
}

中国区域建议

设置 SEARCH_REGION=cn-zh 后，默认引擎链变为 bing → so360 → baidu → sogou， 这四个引擎在大陆网络下均可直连，不需要代理。

关于百度与搜狗的现实情况 在数据中心 / 机房 IP 下，百度即使带上播种 Cookie 也可能被强制图形验证码，搜狗缺少 JS 生成的 SNUID 会话会被 302 拦回。 这两种情况下引擎链会自动转移到 Bing 或 360 搜索，属于预期行为。 如果你在大陆住宅 IP 且希望中文查询优先走原生中文引擎，可设置 SEARCH_LANG_ROUTING=1。

常用起步配置

# 中国大陆，免代理，日志更详细，缓存持久化到磁盘
SEARCH_REGION=cn-zh \
SEARCH_LOG_LEVEL=info \
SEARCH_CACHE_FILE=./.cache/search.json \
npx -y ai-search-mcp

# 墙内访问 DuckDuckGo / Brave / Tavily 时走代理
SEARCH_ENGINE=duckduckgo \
SEARCH_HTTP_PROXY=http://127.0.0.1:7890 \
npx -y ai-search-mcp

下一步

已复制到剪贴板