Skip to content
Back to search

serpapi-mcp

SerpApi MCP Server for Google and other search engine results

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/serpapi/serpapi-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/serpapi/serpapi-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/serpapi--serpapi-mcp/badge.svg)](/listings/serpapi--serpapi-mcp)

HTML

<a href="/listings/serpapi--serpapi-mcp"><img src="/api/listings/serpapi--serpapi-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

SerpApi MCP Server is available as a hosted service at [mcp.serpapi.com](https://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](https://serpapi.com/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](https://serpapi.com/manage-api-key)

Claude Desktop Extension (MCP Bundle)

For a local, one-click install, download the `.mcpb` bundle from the [latest release](https://github.com/serpapi/serpapi-mcp/releases/latest) (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/](mcpb/), plus [.mcpbignore](.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](mcpb/manifest.json), packs the git-tracked files minus [.mcpbignore](.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" }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 222 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # <img src="https://user-images.githubusercontent.com/307597/154772945-1b7dba5f-21cf-41d0-bb2e-65b6eff4aaaf.png" width="30" height="30"/> SerpApi MCP Server
  2. A Model Context Protocol (MCP) server implementation that integrates with [SerpApi](https://serpapi.com) for comprehensive search engine results and data extraction.
  3. [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
  4. [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  5. [![Install in VS Code](https://img.shields.io/badge/Install%20in-VS%20Code-blue?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=serpapi-mcp&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.serpapi.com%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20YOUR_SERPAPI_API_KEY%22%7D%7D)
  6. [![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-blue?logo=cursor)](https://cursor.com/en-US/install-mcp?name=serpapi-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNlcnBhcGkuY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciBZT1VSX1NFUlBBUElfQVBJX0tFWSJ9fQ==)
  7. ## Features
  8. - **Multi-Engine Search**: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and [more](https://serpapi.com/search-engine-apis)
  9. - **Engine Resources**: Per-engine parameter schemas available via MCP resources (see Search Tool)
  10. - **Real-time Weather Data**: Location-based weather with forecasts via search queries
  11. - **Stock Market Data**: Company financials and market data through search integration
  12. - **Dynamic Result Processing**: Automatically detects and formats different result types
  13. - **Flexible Response Modes**: Complete or compact JSON responses
  14. - **JSON Responses (default)**: Structured JSON output with complete or compact modes
  15. - **Markdown Responses**: Cut token usage by 50% on average and by more than 90% for APIs with complex nested JSON.
  16. - **Interactive UI (MCP Apps)**: Opt-in `search_table` and `search_dashboard` tools that render results as an interactive UI in supporting hosts
  17. - **Claude Desktop Extension**: One-click local install from an [MCP Bundle](https://github.com/modelcontextprotocol/mcpb) (`.mcpb`), see below
  18. ## Quick start
  19. SerpApi MCP Server is available as a hosted service at [mcp.serpapi.com](https://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](https://serpapi.com/dashboard).
  20. You can configure Claude Desktop to use the hosted server:
  21. ```json
  22. {
  23. "mcpServers": {
  24. "serpapi": {
  25. "type": "http",
  26. "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
  27. }
  28. }
  29. }
  30. ```
  31. You can also add the hosted server to these MCP clients:
  32. **OpenClaw**
  33. ```bash
  34. openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http
  35. ```
  36. **Claude Code**
  37. ```bash
  38. claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"
  39. ```
  40. **Hermes**
  41. ```bash
  42. hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp
  43. ```
  44. **Codex** (reads the key from `SERPAPI_API_KEY` in your shell)
  45. ```bash
  46. codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY
  47. ```
  48. ### Self-hosting
  49. ```bash
  50. git clone https://github.com/serpapi/serpapi-mcp.git
  51. cd serpapi-mcp
  52. uv sync && uv run src/server.py
  53. ```
  54. Configure Claude Desktop:
  55. ```json
  56. {
  57. "mcpServers": {
  58. "serpapi": {
  59. "type": "http",
  60. "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
  61. }
  62. }
  63. }
  64. ```
  65. Get your API key: [serpapi.com/manage-api-key](https://serpapi.com/manage-api-key)
  66. ### Claude Desktop Extension (MCP bundle)
  67. For a local, one-click install, download the `.mcpb` bundle from the [latest release](https://github.com/serpapi/serpapi-mcp/releases/latest) 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. It provisions Python and dependencies with uv at install time. The same bundle works on macOS, Windows and Linux.
  68. The same stdio entry point works with any local MCP host that launches servers as a subprocess:
  69. ```json
  70. {
  71. "mcpServers": {
  72. "serpapi": {
  73. "command": "uv",
  74. "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
  75. "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
  76. }
  77. }
  78. }
  79. ```
  80. ## Authentication
  81. Two methods are supported:
  82. - **Header-based**: `Authorization: Bearer YOUR_API_KEY` (recommended: the key stays out of URLs and logs)
  83. - **Path-based**: `/YOUR_API_KEY/mcp`, for clients that cannot set headers
  84. **Examples:**
  85. ```bash
  86. # Header-based
  87. curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'
  88. # Path-based
  89. curl "https://mcp.serpapi.com/your_key/mcp" -d '...'
  90. ```
  91. No key is needed to connect, list tools or read resources. `search` and the App tools need one and return an error without it.
  92. ## Search tool
  93. 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](https://serpapi.com/search-api).
  94. Engine parameter schemas are also exposed as MCP resources: `serpapi://engines` (index) and `serpapi://engines/<engine>`.
  95. Clients that support [argument completion](https://gofastmcp.com/servers/completions) 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.
  96. The parameters you can provide are specific for each API engine. Some sample parameters are provided below:
  97. - `params.q` (required): Search query
  98. - `params.engine`: Search engine (default: "google_light")
  99. - `params.location`: Geographic filter
  100. - `params.output`: Response format; omit for JSON (default), or set to `"md"` for Markdown
  101. - `mode`: Response mode; `"compact"` removes metadata from JSON, while Markdown is returned unchanged
  102. - ...see other parameters on the [SerpApi API reference](https://serpapi.com/search-api)
  103. **Examples:**
  104. ```json
  105. {"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
  106. {"name": "search", "arguments": {"params": {"q": "weather in London"}}}
  107. {"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
  108. {"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
  109. {"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
  110. {"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
  111. {"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
  112. {"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
  113. {"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
  114. {"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
  115. {"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}
  116. ```
  117. **Supported engines:** Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay, and more (see `serpapi://engines`).
  118. **Result types:** Answer boxes, organic results, news, images, shopping - automatically detected and formatted.
  119. 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](https://modelcontextprotocol.io/specification/2025-06-18/server/tools).
  120. `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](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr).
  121. - [Google Flights](https://serpapi.com/google-flights-api): 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.
  122. - [Google Hotels](https://serpapi.com/google-hotels-api): 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.
  123. - [Google Maps Directions](https://serpapi.com/google-maps-directions-api): missing start and destination addresses. Coordinates or place data IDs already supplied satisfy the corresponding endpoint.
  124. - 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.
  125. If an answer introduces another requirement, the tool lists the remaining fields for the agent to supply in a new call. Forms support strings, numbers, booleans, and single-choice fields; unsupported complex fields receive the missing-parameter error. Unknown engines pass through to SerpApi.
  126. ## Extract tool
  127. The `extract` tool reads web pages and returns their content as structured JSON or Markdown. You can extract a single page, discover a website's URLs, or crawl multiple pages. Find all available parameters on the [Extract API reference](https://serpapi.com/extract-api) or in the `serpapi://engines/extract` resource.
  128. Some parameters you can provide:
  129. - `params.url` (required): Page or website URL
  130. - `params.mode`: Extraction mode; `"scrape"` (default) reads one page, `"map"` discovers URLs, and `"crawl"` extracts multiple pages
  131. - `params.include_markdown`: Include the page's content as Markdown; defaults to `true` for scrape and crawl, or set to `false` to disable it
  132. - `params.output`: Response format; defaults to `"json"` in complete mode and `"md"` in compact mode. Set it explicitly to override the format.
  133. - `params.max_pages`: Maximum pages to crawl, including the starting page (default: 10, maximum: 100)
  134. - `params.json_restrictor`: Choose which fields to return, such as `"markdown,error"`
  135. - `mode`: Response mode; `"complete"` (default) returns the full response. `"compact"` defaults to native Markdown. With an explicit `params.output="json"`, single-page compact extraction keeps the top-level `markdown` field when present and retains API errors. Responses without Markdown, including results redirected to another engine, keep their data with metadata removed. Explicit `params.json_restrictor` values and `params.include_markdown=false` take precedence when using JSON. For map and crawl, compact JSON removes metadata. Markdown output is returned unchanged.
  136. **Examples:**
  137. ```json
  138. {"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
  139. {"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
  140. {"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
  141. {"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
  142. {"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}
  143. ```
  144. For a single page's content as native Markdown, use `mode="compact"`. Add `params.output="json"` to receive JSON containing the `markdown` field instead. Complete JSON includes that field by default; crawl JSON includes it in each `pages` entry. Setting `params.output="json"` and `params.include_markdown=false` keeps the remaining structured fields without Markdown.
  145. Crawling consumes one search credit per successfully extracted page on an uncached request. Use `params.max_pages` to limit how many pages are extracted.
  146. ## Interactive UI (MCP apps)
  147. The `search` tool returns JSON by default. For hosts that support the [MCP Apps extension](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp) (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:
  148. - `search_table`: organic results as a sortable, searchable table.
  149. - `search_dashboard`: summary metrics, a source-breakdown chart, and a results table with a click-to-expand detail panel.
  150. Both accept the same `params` as `search`. Hosts that don't support MCP Apps simply ignore these tools.
  151. ## Troubleshooting
  152. - **"Missing API key"**: Include key in URL path `/{YOUR_KEY}/mcp` or header `Bearer YOUR_KEY`
  153. - **"Invalid key"**: Verify at [serpapi.com/dashboard](https://serpapi.com/dashboard)
  154. - **"Rate limit exceeded"**: Wait or upgrade your SerpApi plan
  155. - **"No results"**: Try different query or engine
  156. ## Privacy policy
  157. - **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.
  158. - **Forwarded**: each search goes to `serpapi.com` with your API key; results come back unchanged. See the [SerpApi Privacy Policy](https://serpapi.com/legal#privacy-policy) for how SerpApi handles searches and accounts.
  159. - **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.
  160. - **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`.
  161. - **Contact**: [privacy@serpapi.com](mailto:privacy@serpapi.com), or open an [issue](https://github.com/serpapi/serpapi-mcp/issues).
  162. ## Contributing
  163. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, schema refresh commands, testing, Docker and MCP Bundle builds, and releases.
  164. ## License
  165. MIT License - see [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.