Skip to main content
Glama
deenesjakoruzh
serpapi

SerpApi MCP Server

by serpapi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

SerpApi MCP Server

A Model Context Protocol (MCP) server implementation that integrates with SerpApi for comprehensive search engine results and data extraction.

Python 3.13+ MIT License Install in VS Code Install in Cursor

Features

  • Multi-Engine Search: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and more

  • Engine Resources: Per-engine parameter schemas available via MCP resources (see Search Tool)

  • Real-time Weather Data: Location-based weather with forecasts via search queries

  • Stock Market Data: Company financials and market data through search integration

  • Dynamic Result Processing: Automatically detects and formats different result types

  • Flexible Response Modes: Complete or compact JSON responses

  • JSON Responses (default): Structured JSON output with complete or compact modes

  • Markdown Responses: Cut token usage by 50% on average and by more than 90% for APIs with complex nested JSON.

  • Interactive UI (MCP Apps): Opt-in search_table and search_dashboard tools that render results as an interactive UI in supporting hosts

  • Claude Desktop Extension: One-click local install from an MCP Bundle (.mcpb), see below

Related MCP server: SearXNG MCP Server

Quick Start

SerpApi MCP Server is available as a hosted service at mcp.serpapi.com. In order to connect to it, you need to provide an API key. You can find your API key on your SerpApi dashboard.

You can configure Claude Desktop to use the hosted server:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

You can also add the hosted server to these MCP clients:

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex (reads the key from SERPAPI_API_KEY in your shell)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

Self-Hosting

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Configure Claude Desktop:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Get your API key: serpapi.com/manage-api-key

Claude Desktop Extension (MCP Bundle)

For a local, one-click install, download the .mcpb bundle from the latest release (or build it as below) and open it with Claude Desktop (or drop it onto Settings → Extensions). Claude Desktop asks for your SerpApi API key during install, stores it as a sensitive setting, and runs the server locally over stdio. The bundle uses the MCPB uv runtime: it ships only the source, pyproject.toml and uv.lock, and Claude Desktop provisions Python and the locked dependencies with uv at install time, so nothing is vendored and one bundle works on macOS, Windows and Linux.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Everything bundle-related lives in mcpb/, plus .mcpbignore at the project root. The build regenerates the engine schemas from the SerpApi Playground (--no-rebuild-engines bundles engines/ from the working tree instead), validates mcpb/manifest.json, packs the git-tracked files minus .mcpbignore with the manifest at the bundle root, then installs it into a temp dir and starts it over stdio to make sure it works (--no-smoke skips that last step). The bundle is only built at release time: pushing a v<version> tag runs the release workflow, which runs the test suite and then deploys the hosted server, publishes the MCP Registry entry, and builds the bundle and attaches it to the GitHub release. Pull requests run the manifest and stdio entry point tests in tests/test_mcpb.py but do not pack a bundle.

The same stdio entry point works with any local MCP host that launches servers as a subprocess:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

Authentication

Two methods are supported:

  • Header-based: Authorization: Bearer YOUR_API_KEY (recommended: the key stays out of URLs and logs)

  • Path-based: /YOUR_API_KEY/mcp, for clients that cannot set headers

Examples:

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

No key is needed to connect, list tools or read resources. search and the App tools need one and return an error without it.

Search Tool

The MCP server has one main Search Tool that supports all SerpApi engines and result types. You can find all available parameters on the SerpApi API reference. Engine parameter schemas are also exposed as MCP resources: serpapi://engines (index) and serpapi://engines/<engine>. Clients that support argument completion can request engine-name suggestions for serpapi://engines/{engine_name}. For example, the prefix google_f suggests matching engine identifiers. This completes the resource URI parameter, not arbitrary search queries.

The parameters you can provide are specific for each API engine. Some sample parameters are provided below:

  • params.q (required): Search query

  • params.engine: Search engine (default: "google_light")

  • params.location: Geographic filter

  • params.output: Response format; omit for JSON (default), or set to "md" for Markdown

  • mode: Response mode; "compact" removes metadata from JSON, while Markdown is returned unchanged

  • ...see other parameters on the SerpApi API reference

Examples:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

Supported Engines: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and more (see serpapi://engines).

Result Types: Answer boxes, organic results, news, images, shopping - automatically detected and formatted.

Search responses preserve the existing MCP structuredContent.result string and include the same string in text content. For JSON output, result contains serialized JSON; existing clients can continue parsing it with JSON.parse(response.structuredContent.result). For Markdown output, it contains the unchanged Markdown. Errors and cancellations use the same wrapper. Search execution failures set isError: true; clients using FastMCP's high-level call_tool() should handle ToolError, or use call_tool_mcp() to inspect the result flag. See MCP tool results.

search uses the engine catalog and engine-specific rules to identify missing parameters. Supporting MCP 2026-07-28 clients receive a form before any search runs. Accepted answers are validated; decline or cancellation runs no search. Legacy clients and clients without form elicitation receive an error listing the missing parameters so the agent can ask in conversation. See MCP input requests.

  • Google Flights: departure and arrival identifiers, departure date, and a return date for round trips. Dates and airport identifiers are checked. Token-based searches, multi-city itineraries, and selected_flights_json retain their existing behavior.

  • Google Hotels: destination or hotel query, check-in date, and check-out date. Check-out must follow check-in. Guest counts and other optional filters keep the caller's values or the API defaults.

  • Google Maps Directions: missing start and destination addresses. Coordinates or place data IDs already supplied satisfy the corresponding endpoint.

  • Other catalog engines use their required fields, such as YouTube's search_query, Yelp's find_loc, and Amazon's k. Engine rules account for known defaults and alternatives, including Amazon category nodes, eBay categories, and Google Scholar citation searches.

The form is derived from the original arguments on each request. It uses no requestState or process-local continuation storage, so a retry can run on another replica without a shared state-protection key. Authentication is applied on every HTTP request, and only answers for requested fields are used. If an answer introduces another requirement, the tool lists the remaining fields for the agent to supply in a new call.

To extend guided search, add required fields, descriptions, types, and options to the engine's engines/<engine>.json file. Add an EngineInputRules entry in src/engine_input_rules.py when requirements depend on other parameters, defaults, or alternatives. The shared MCP handler in src/search_input.py needs no engine-specific branches. Forms support strings, numbers, booleans, and single-choice fields; unsupported complex fields receive the missing-parameter error. Unknown engines pass through to SerpApi.

Interactive UI (MCP Apps)

The search tool returns JSON by default. For hosts that support the MCP Apps extension (SEP-1865), two opt-in tools render results as an interactive UI directly in the conversation, so the bulk SERP JSON never enters the model's context window:

  • search_table: organic results as a sortable, searchable table.

  • search_dashboard: summary metrics, a source-breakdown chart, and a results table with a click-to-expand detail panel.

Both accept the same params as search. Hosts that don't support MCP Apps simply ignore these tools.

Preview them locally without an MCP host:

uv run fastmcp dev apps src/server.py

Development

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Troubleshooting

  • "Missing API key": Include key in URL path /{YOUR_KEY}/mcp or header Bearer YOUR_KEY

  • "Invalid key": Verify at serpapi.com/dashboard

  • "Rate limit exceeded": Wait or upgrade your SerpApi plan

  • "No results": Try different query or engine

Privacy Policy

  • Sent: only the parameters the MCP host passes to a tool call. The server never sees the rest of the conversation, or files, memory or history on the host.

  • Forwarded: each search goes to serpapi.com with your API key; results come back unchanged. See the SerpApi Privacy Policy for how SerpApi handles searches and accounts.

  • Kept: mcp.serpapi.com records request metrics (method, status code, duration) and stores no queries or results. A key in the URL path can appear in request logs, so prefer the header.

  • Local bundle: the Claude Desktop extension runs on your machine, keeps the key in Claude Desktop's settings and calls serpapi.com directly. Nothing passes through mcp.serpapi.com.

  • Contact: privacy@serpapi.com, or open an issue.

Contributing

  1. Fork the repository

  2. Create your feature branch: git checkout -b feature/amazing-feature

  3. Install dependencies: uv install

  4. Make your changes

  5. Commit changes: git commit -m 'Add amazing feature'

  6. Push to branch: git push origin feature/amazing-feature

  7. Open a Pull Request

License

MIT License - see LICENSE file for details.

Available Tools

3 tools
search_dashboardSerpApi search (dashboard)A
Read-only

Interactive dashboard variant of search: returns summary metrics, a source breakdown chart, and a results table with a click-to-expand detail panel, all rendered in the conversation. Same params as search. Use for a richer visual overview of a query's results. Automatically selects an engine-specific dashboard when available (e.g. google_flights gets price intelligence charting).

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsNo

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, non-destructive, and open-world hints. The description adds behavior beyond these: it describes the interactive rendering in conversation and the automatic selection of engine-specific dashboards (e.g., google_flights), which is valuable context. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with zero fluff. The key differentiator (dashboard variant) is front-loaded, followed by output details and usage guidance. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a variant tool, the description is complete: it states what it returns, when to use it, and where to get parameter details. It does not mention pagination or error handling, but these are not critical for a read-only dashboard tool with annotations already covering safety.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one opaque `params` object with 0% coverage. The description compensates by stating 'Same params as `search`', directing the agent to the sibling's schema for parameter details. This is a pragmatic and effective way to convey parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is an interactive dashboard variant of `search`, enumerating the specific outputs (summary metrics, source breakdown chart, results table with expandable detail panel). This distinguishes it from the sibling tools `search` and `search_table` without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It says 'Use for a richer visual overview of a query's results', giving clear context for when to select this tool. It also notes 'Same params as `search`', implying the simpler `search` tool may be used for non-visual needs, though it does not explicitly name alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_tableSerpApi search (table)A
Read-only

Interactive UI variant of search: returns organic results as a sortable, searchable table rendered in the conversation. Same params as search. Use when the host supports MCP Apps and the user wants to browse results visually rather than read JSON.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsNo

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and destructiveHint, covering the safety profile. The description adds useful behavioral context beyond that: results are organic, the table is sortable/searchable, it renders in the conversation, and it depends on MCP Apps support. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The first sentence front-loads the core purpose and sibling relationship; the second gives the usage condition. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a thin wrapper around `search`, the description covers purpose, differentiation, when to use it, and the parameter relationship. Annotations cover read-only safety, and there is no output schema to document. It only lacks explicit handling of what happens when the host lacks MCP Apps support, and its parameter semantics depend on the parent tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single opaque `params` object with additionalProperties true and 0% description coverage, so the description must compensate. Saying 'Same params as `search`' adds meaning by reference and tells the agent to reuse another tool's parameter definitions, but it does not enumerate or describe those parameters, leaving the payload underspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's behavior: it returns organic results as an interactive, sortable/searchable table rendered in the conversation. It explicitly positions itself as a 'variant of `search`', which distinguishes it from the sibling tool without needing to open any schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete use condition: 'Use when the host supports MCP Apps and the user wants to browse results visually rather than read JSON.' It points to the alternative `search`, but does not explicitly state when not to use this tool or address the `search_dashboard` sibling, so it stops short of fully explicit routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev2.0.0
    • Changedsearch3 fields changed
      • removedInput schema / properties / params / additionalProperties
        Removed value: -true
      • addedInput schema / properties / params / anyOf
        Added value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
      • removedInput schema / properties / params / type
        Removed value: -"object"
  2. 3 tool updatesv1.0.3
    • First observedsearch
    • First observedsearch_dashboard
    • First observedsearch_table
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 3 tools

Disambiguation4/5

The three tools are clearly labeled as base search, dashboard, and table variants, with descriptions explaining when to use each. However, they all wrap the same underlying SerpApi search, so semantic overlap is inherent and an agent must rely on the presentation-focused descriptions to select correctly.

Naming Consistency5/5

All tool names follow a consistent pattern: the base 'search' plus descriptive 'search_dashboard' and 'search_table' variants. There is no mixing of naming conventions or styles.

Tool Count4/5

Three tools is minimal but appropriate for a search API wrapper: one universal search operation and two UI presentation variants. The count is lean but not deficient.

Completeness4/5

The search tool covers all SerpApi engines and output modes, so the core domain is fully covered with no dead ends. Minor gaps like explicit pagination or account-related operations are not exposed, but they are not essential to the server's purpose.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • SearXNG MCP Server

    tobioffice
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that integrates with the SearXNG API to provide comprehensive web search capabilities with features like time filtering, language selection, and safe search. It also enables users to fetch and convert web content from specific URLs into markdown format.
    2
    10 npm
    4
    MIT

  • SearXNG MCP Server

    aicrafted
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables web search capabilities by integrating with a SearXNG instance to aggregate results from over 130 engines. It allows users to perform filtered searches across categories like news, science, and social media while supporting advanced parameters for language and time range.
    9
    MIT

  • mcp-searxng

    atomlong
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that integrates the SearXNG API for web search and URL content extraction with advanced features like pagination, caching, and proxy support.
    4
    8,974 npm
    2
    MIT

Appeared in Searches