OpenSERP

@openserp/mcp

在六种搜索引擎（Google、Bing、Yandex、Baidu、DuckDuckGo、Ecosia）上进行实时搜索、图片搜索，并提取单个或批量页面内容，供 AI Agent 使用。结果会保留来源搜索引擎和排名。可连接可自托管的 OpenSERP 服务或 OpenSERP Cloud。

未设置 OPENSERP_API_KEY 时，服务会在 http://localhost:7000 使用 OSS 模式，并写入：

[openserp-mcp] No OPENSERP_API_KEY set - using OSS mode at http://localhost:7000.
[openserp-mcp] Get an API key: https://openserp.org/dashboard/keys
[openserp-mcp] Docs: https://openserp.org/docs | Issues: https://github.com/openserpapi/mcp/issues

设置 OPENSERP_API_KEY 以使用 OpenSERP Cloud。可在 https://openserp.org/dashboard/keys 获取 API 密钥。设置 OPENSERP_BASE_URL 可指定其他兼容的 OpenSERP API 基础 URL。

安装

npm install -g @openserp/mcp

也可以直接运行，无需安装：

npx -y @openserp/mcp --stdio

工具

工具	适用场景
search	搜索引擎很重要时（例如，俄语用 Yandex，中文用 Baidu），或需要使用 start 翻页时
any_search	想按指定顺序使用首选搜索引擎及备用引擎时
fast_search	任意搜索引擎都可以时；会选择运行状况最佳、速度最快的引擎
mega_search	需要比较搜索引擎或扩大覆盖范围时；结果会保留搜索引擎和排名
image_search	从一个搜索引擎搜索图片
mega_image	合并多个搜索引擎的图片结果
extract	将单个页面读取为 Markdown
batch_extract	在一次调用中读取多个页面（最多 20 个）；某个 URL 失败不会导致整个批次失败
list_engines	搜索持续失败且需要找到运行状况良好的搜索引擎时
get_usage	查看 Cloud 额度余额或上次调用的费用时

extract 和 batch_extract 会截短长页面以适配 Agent 的上下文：每页 20,000 个字符，或整个批次共享 40,000 个字符（每个 URL 至少 2,000 个字符）。截短内容末尾会附上 [truncated: ...]，并通过 truncated / metadata.truncated 标记。传入 maxChars 可读取更多内容。

快速示例

让 MCP 客户端执行以下操作：

• 搜索 Google 上的最新文档并返回排名前 5 的 URL。
• 比较 Google 和 Bing 对某个 SEO 关键词的搜索结果。
• 将 URL 中的内容提取为干净的 Markdown，再传给大模型。
• 使用 batch_extract 一次性从多个来源获取依据，最多可在一次往返中处理 20 个 URL；失效链接会返回错误条目，而不会导致整个批次失败。
• 传入 region: "DE"，以本地访客身份读取受地理位置限制的页面。
• 使用 get_usage 查看剩余的 Cloud 额度。

Cloud 搜索参数

Cloud 请求使用 Authorization: Bearer 和 OPENSERP_API_KEY。翻页时使用 start，并保持 limit: 10；当 has_more 为 true 时，传入上次响应中的 pagination.next_start。Google、Bing 和 Yandex 的 start 必须是 10 的倍数；Baidu 支持较早的页面，Ecosia 支持任意偏移量，而 DuckDuckGo 仅支持第一页。mega_search 使用 mode: "balanced" 时不接受 start > 0；要获取后续页面，请使用 search、any_search 或 fast_search。

Cloud 网页搜索支持在 Google 和 Ecosia 上使用 date: "20250101..20251231"。不支持的偏移量或日期筛选条件会返回 400 invalid_request，且不收费；请调整请求后重试。

list_engines 会返回 Cloud 功能以及运行状态 status。省略 engines 可使用默认值。Any 会按指定顺序启动搜索引擎，并行尝试耗时较长的请求；Fast 会优先考虑近期运行状况和延迟。查看 meta.engine_used 获取胜出的搜索引擎；engines_tried 和 engines_skipped 可能不存在。

工具错误会包含公开的 HTTP 状态码、错误代码、请求 ID，以及可用时的重试延迟。对于 429 和 503，请遵守 retry_after；503 engine_unavailable 会附带 60 秒的延迟。服务不会自动重试。

Claude Desktop

本地 OSS 模式：

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"]
    }
  }
}

Cloud 模式：

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"],
      "env": {
        "OPENSERP_API_KEY": "osk_live_..."
      }
    }
  }
}

Cursor

对于 stdio 用法，添加 MCP 服务条目：

{
  "mcpServers": {
    "openserp": {
      "command": "npx",
      "args": ["-y", "@openserp/mcp"],
      "env": {
        "OPENSERP_API_KEY": "osk_live_..."
      }
    }
  }
}

对于远程风格的 HTTP 用法，运行：

npx -y @openserp/mcp --http --host 127.0.0.1 --port 3333

然后将支持流式 HTTP 的 MCP 客户端指向：

http://127.0.0.1:3333/mcp

仍使用旧版 SSE 传输的客户端可以连接到：

http://127.0.0.1:3333/sse

环境

• OPENSERP_API_KEY：来自 https://openserp.org/dashboard/keys 的 Cloud API 密钥。
• OPENSERP_BASE_URL：API 基础 URL 覆盖值。
• OPENSERP_BACKEND：可选的后端提示，oss 或 cloud。
• OPENSERP_TIMEOUT_MS：SDK 请求超时，单位为毫秒。
• HOST：HTTP 主机，默认为 127.0.0.1。
• PORT：HTTP 端口，默认为 3333。

资源

• OpenSERP Cloud 文档
• MCP 服务源代码
• JavaScript SDK