mcp-searchapi

An MCP server for SearchApi.io. Eight search engines exposed as discrete tools, returning trimmed structured results instead of raw SERP payloads.

npx -y mcp-searchapi

Why this exists

Two SearchApi MCP packages were already on npm when this was written. Both are single-version releases from mid-2025 that have not been updated since, neither has a test suite, and one of them targets SearchAPI**.site**, a different product. So this is not a third copy of the same thing:

One tool per engine, not one search tool with a mode flag. A model picks google_jobs correctly far more often than it picks search(engine="google_jobs"). Every parameter carries a description written as guidance, because those descriptions are the prompt the model actually reads.

Trimmed structured output. SearchApi returns results under a different key per engine (organic_results, local_results, shopping_results, videos, jobs), each with a different field set, and the payloads are large. Measured against live responses on 7 August 2026:

The percentage matters less than the ceiling: whatever the engine sends back, a page of results stays under 8KB. Handing a model 171KB of ad blocks, favicons and pagination tokens spends its context window on things it will never use.

Every result normalises to a common core (position, title, url, snippet) plus the extras that matter for that engine: price and rating for shopping, coordinates and opening state for maps, company and posting date for jobs, channel and view count for YouTube, citation counts for Scholar.

Related MCP server: evo-scry

Setup

Get a key at searchapi.io. The free tier is 100 searches a month.

Claude Desktop

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

{
  "mcpServers": {
    "searchapi": {
      "command": "npx",
      "args": ["-y", "mcp-searchapi"],
      "env": { "SEARCHAPI_API_KEY": "your-key" }
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "searchapi": {
      "command": "npx",
      "args": ["-y", "mcp-searchapi"],
      "env": { "SEARCHAPI_API_KEY": "your-key" }
    }
  }
}

VS Code

.vscode/mcp.json:

{
  "servers": {
    "searchapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-searchapi"],
      "env": { "SEARCHAPI_API_KEY": "your-key" }
    }
  }
}

Hosted

SEARCHAPI_API_KEY=your-key npx -y mcp-searchapi --http --port 3000

Serves streamable HTTP at /mcp and a health check at /health. Stateless, so it scales horizontally without sticky sessions.

Tools

Parameters

query is required everywhere. limit (default 10, max 50) caps what comes back to the model. The rest are offered only on the engines that accept them:

google_jobs deliberately does not offer gl: the API rejects country codes on that engine (gl=ie returns HTTP 400 Unsupported value). Use location instead. Advertising a parameter the API will reject is worse than not having it, because the model has no way to discover the constraint.

Example

google_jobs(query: "backend engineer", location: "Dublin,Ireland", limit: 3)

{
  "engine": "google_jobs",
  "query": "backend engineer",
  "totalResults": 10,
  "results": [
    {
      "position": 1,
      "title": "Backend Engineer",
      "url": "https://...",
      "company": "Example Ltd",
      "location": "Dublin, Ireland",
      "via": "LinkedIn",
      "postedAt": "2 days ago",
      "scheduleType": "Full-time",
      "snippet": "..."
    }
  ]
}

totalResults reports what the engine returned, not what was kept, so the model can tell there is more available behind a higher limit.

Errors

Failures come back as tool errors with something actionable, not a bare status code:

Development

npm install
npm test           # 77 tests, no network
npm run typecheck
npm run build

SEARCHAPI_API_KEY=... node scripts/smoke.mjs   # end-to-end, costs 1 search

Tests run against real captured API responses in test/fixtures/, one per engine plus an empty-result case, so they exercise the shapes the API actually returns rather than the shapes it was assumed to return. Nothing in npm test touches the network.

Adding an engine is a data change: append an entry to ENGINES in src/engines.ts with its result key, supported parameters and a normaliser. The server registers tools from that registry.

Licence

MIT