Skip to main content
Glama
SerpBase MCP

SerpBase MCP

Official
by serpbase-dev

SerpBase MCP

中文文档

Google SERP API MCP server for AI agents, search grounding, RAG, SEO tools, and local business data workflows.

Connect the SerpBase Google Search, Images, News, Videos, and Maps APIs to any AI agent that supports MCP.

Use this server when you want to:

  • Give Claude, Codex, Cursor, Cline/Roo, Continue, or another MCP client real-time Google search.

  • Ground RAG, market research, SEO, competitor monitoring, or brand monitoring workflows with structured SERP data.

  • Query Google Images, News, Videos, Maps local search, and Maps place details as JSON.

Features

MCP tool

SerpBase API

Use case

serpbase_search

/google/search

Google Search results, organic links, related searches, knowledge graph, and other SERP modules

serpbase_images

/google/images

Image URLs, thumbnails, source pages, and domains

serpbase_news

/google/news

News titles, publishers, time text, snippets, and thumbnails

serpbase_videos

/google/videos

Video links, sources, durations, time text, and thumbnails

serpbase_maps_search

/google/maps/search

Google Maps local place search

serpbase_maps_detail

/google/maps/detail

Place detail lookup by feature_id

Related MCP server: gemini-search-mcp

Get an API key

  1. Open SerpBase API Keys.

  2. Create or copy an API key.

  3. Pass it to your MCP client as an environment variable:

SERPBASE_API_KEY=your_serpbase_api_key

Do not commit API keys to public repositories.

Installation

Install from GitHub:

git clone https://github.com/serpbase-dev/serpbase-mcp.git
cd serpbase-mcp
python -m venv .venv

macOS / Linux:

source .venv/bin/activate
pip install -e .

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -e .

You can also run it as a Python module:

python -m pip install -e .
python -m serpbase_mcp

MCP configuration

Generic config

If the serpbase-mcp command is available on PATH:

{
  "mcpServers": {
    "serpbase": {
      "command": "serpbase-mcp",
      "env": {
        "SERPBASE_API_KEY": "your_serpbase_api_key"
      }
    }
  }
}

If the command is not on PATH, run the module directly:

{
  "mcpServers": {
    "serpbase": {
      "command": "python",
      "args": ["-m", "serpbase_mcp"],
      "cwd": "/absolute/path/to/serpbase-mcp",
      "env": {
        "SERPBASE_API_KEY": "your_serpbase_api_key"
      }
    }
  }
}

Windows path example:

{
  "mcpServers": {
    "serpbase": {
      "command": "python",
      "args": ["-m", "serpbase_mcp"],
      "cwd": "C:\\Users\\you\\work\\serpbase-mcp",
      "env": {
        "SERPBASE_API_KEY": "your_serpbase_api_key"
      }
    }
  }
}

Claude Desktop

Add the mcpServers block above to your Claude Desktop config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop. The serpbase_* tools should appear in the tool list.

Cursor / Cline / Roo / Continue

The UI differs by client, but the config is the same: add a stdio MCP server named serpbase, set command to serpbase-mcp or python -m serpbase_mcp, and pass SERPBASE_API_KEY in env.

Usage examples

Call serpbase_search:

{
  "query": "python asyncio tutorial",
  "hl": "en",
  "gl": "us",
  "page": 1
}

Prompt example:

Use SerpBase to search for recent articles about Python asyncio and summarize the top results with links.

Google Images

Call serpbase_images:

{
  "query": "iphone 15 pro blue",
  "hl": "en",
  "gl": "us",
  "page": 1
}

Important fields: images[].image_url, thumbnail_url, link, and domain.

Google News

Call serpbase_news:

{
  "query": "apple event",
  "hl": "en",
  "gl": "us",
  "page": 1
}

Important fields: news[].title, source, time, published_at, snippet, and link.

Google Videos

Call serpbase_videos:

{
  "query": "python asyncio tutorial",
  "hl": "en",
  "gl": "us",
  "page": 1
}

Important fields: videos[].title, source, duration, time, and link.

Call serpbase_maps_search:

{
  "query": "coffee",
  "hl": "en",
  "gl": "us",
  "page": 1,
  "lat": 37.7749,
  "lng": -122.4194,
  "zoom": 14
}

lat and lng must be sent together. Important fields: places[].name, feature_id, rating, address, phone, website, google_maps_url, latitude, and longitude.

Google Maps place detail

Get a feature_id from serpbase_maps_search, then call serpbase_maps_detail:

{
  "feature_id": "0x8085809c2c6fdc63:0x4b3f2d70e4f5a123",
  "hl": "en",
  "gl": "us"
}

Environment variables

Variable

Required

Default

Description

SERPBASE_API_KEY

Yes

None

SerpBase API key

SERPBASE_BASE_URL

No

https://api.serpbase.dev

Override only for testing or private gateways

SERPBASE_TIMEOUT

No

30

Request timeout in seconds

SERPBASE_SOURCE

No

serpbase-mcp

Value sent as X-SerpBase-Source

Local tests

pip install -e ".[dev]"
python -m pytest

Quick import check:

python -c "from serpbase_mcp.broker import _TOOLS; print([t.name for t in _TOOLS])"

Troubleshooting

The client cannot find serpbase-mcp

Use module mode:

{
  "command": "python",
  "args": ["-m", "serpbase_mcp"],
  "cwd": "/absolute/path/to/serpbase-mcp"
}

SERPBASE_API_KEY is not set

Add the key to your MCP server environment:

{
  "SERPBASE_API_KEY": "your_serpbase_api_key"
}

Restart the MCP client after changing the config.

status: 1020

The account does not have enough credits. Add credits in the SerpBase dashboard or use another valid API key.

Ask the agent to cite the link, url, display_url, or google_maps_url fields returned by SerpBase.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Go-based MCP server that provides comprehensive access to the Serper Google Search API, including tools for images, news, maps, and scholar results. It also features a dedicated endpoint for scraping webpage content directly.
      5 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for web search powered by Google AI Mode (Gemini). Enables any AI agent to search the web in real-time for free and without rate limits.
      2
      189
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Free, unlimited web search MCP server powered by Google AI Mode (Gemini) without API key. Provides real-time search results for AI agents like Claude, Cursor, and Windsurf.
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server exposing 35 web scraping and SERP tools for general scraping, Google services, e-commerce sites, social media, and search engines. Enables MCP clients like Claude to scrape web pages and search results via natural language.
      35
      61 npm
      MIT