OpenSERP

@openserp/mcp

Live search on six engines (Google, Bing, Yandex, Baidu, DuckDuckGo, Ecosia), image search and single/batch page extraction for AI agents. Results keep the source engine and rank. Runs against a self-hosted OpenSERP server or OpenSERP Cloud.

When OPENSERP_API_KEY is not set, the server uses OSS mode at http://localhost:7000 and writes:

[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

Set OPENSERP_API_KEY to use OpenSERP Cloud. API keys are available at https://openserp.org/dashboard/keys. Set OPENSERP_BASE_URL to target another compatible OpenSERP API base URL.

Install

npm install -g @openserp/mcp

You can also run it without installing:

npx -y @openserp/mcp --stdio

Tools

Tool	Use it when
search	The engine matters (Yandex for Russian, Baidu for Chinese), or you page with start
any_search	You want a preferred engine with fallbacks, in your order
fast_search	Any engine will do; picks the healthiest, fastest one
mega_search	You compare engines or want wider coverage; results keep engine and rank
image_search	Images from one engine
mega_image	Images merged from several engines
extract	Reading one page as Markdown
batch_extract	Reading several pages (up to 20) in one call; a failed URL doesn't fail the batch
list_engines	Searches keep failing and you need a healthy engine
get_usage	Checking the Cloud credit balance or what the last call cost

extract and batch_extract cut long pages to fit an agent's context: 20,000 characters per page, or 40,000 shared across a batch (at least 2,000 per URL). Cut content ends with a [truncated: ...] line and is flagged (truncated / metadata.truncated). Pass maxChars to read more.

Quick Examples

Ask your MCP client to:

• Search Google for current docs and return the top 5 URLs.
• Compare Google and Bing results for an SEO keyword.
• Extract clean Markdown from a URL before passing it to an LLM.
• Ground an answer in several sources at once with batch_extract - up to 20 URLs in one round-trip, where a dead link returns an error item instead of failing the batch.
• Read a geo-fenced page as a local visitor by passing region: "DE".
• Check remaining Cloud credits with get_usage.

Cloud search parameters

Cloud requests use Authorization: Bearer with OPENSERP_API_KEY. For paging, use start and keep limit: 10; pass the previous response's pagination.next_start while has_more is true. Google, Bing, and Yandex take multiples of 10; Baidu supports early pages, Ecosia any offset, and DuckDuckGo only the first page. mega_search with mode: "balanced" rejects start > 0; use search, any_search, or fast_search for later pages.

Cloud web search supports date: "20250101..20251231" on Google and Ecosia. Unsupported offsets or date filters return 400 invalid_request without charge; adjust the request before retrying.

list_engines returns Cloud capabilities plus operational status. Omit engines to use defaults. Any starts engines in your order, overlapping slow attempts; Fast prioritizes recent health and latency. Read meta.engine_used for the winner; engines_tried and engines_skipped may be absent.

Tool errors include the public HTTP status, error code, request ID, and retry delay when present. Honor retry_after for 429 and 503; 503 engine_unavailable carries a 60-second delay. The server does not retry automatically.

Claude Desktop

Local OSS mode:

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

Cloud mode:

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

Cursor

For stdio use, add an MCP server entry:

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

For remote-style HTTP use, run:

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

Then point a streamable HTTP MCP client to:

http://127.0.0.1:3333/mcp

Clients that still use the older SSE transport can connect to:

http://127.0.0.1:3333/sse

Environment

• OPENSERP_API_KEY: Cloud API key from https://openserp.org/dashboard/keys.
• OPENSERP_BASE_URL: API base URL override.
• OPENSERP_BACKEND: Optional backend hint, oss or cloud.
• OPENSERP_TIMEOUT_MS: SDK request timeout in milliseconds.
• HOST: HTTP host, default 127.0.0.1.
• PORT: HTTP port, default 3333.

Resources

• OpenSERP Cloud docs
• MCP server source
• JavaScript SDK