SERP API & MCP docs

The SERP API crawls Google and returns the top 100 organic results, AI Overviews, and SERP features for a keyword, with geo and device targeting. Submit a search, then poll for the result in your preferred format.

Base URL: https://serp-api.hoangha.shop

Every request needs an API key, sent in the X-API-Key header. Keys carry a tier and a monthly quota. Generate and revoke keys from the admin SERP API dashboard; the raw key is shown once at creation.

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxx

Submit a search

POST/v1/search

curl -X POST https://serp-api.hoangha.shop/v1/search \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "best running shoes",
    "location": "Hanoi, Vietnam",
    "device": "desktop",
    "async": true
  }'

# -> { "job_id": "9f3c...", "status": "queued", "cached": false }

The AI Overview is captured on every search by default and fetches no extra result page, but it does add a render wait. Pass capture_aio: false to skip it for a faster crawl.

Fetch results

GET/v1/search/{job_id}?output=serpapi

curl "https://serp-api.hoangha.shop/v1/search/9f3c...?output=serpapi" \
  -H "X-API-Key: sk_live_..."

# Still running -> { "job_id": "9f3c...", "status": "running" }
# Done -> parsed results in the requested format

Usage & quota

GET/v1/usage returns the key's tier, monthly quota, usage this month, and remaining quota.

Already using SerpApi?

We also serve serpapi.com's own paths, parameter names and response envelope at the root, so an existing client only changes its host. Both official Python clients keep the base URL in a class attribute:

import serpapi
serpapi.HTTPClient.BASE_DOMAIN = "https://serp-api.hoangha.shop"       # serpapi-python
# GoogleSearch.BACKEND = "https://serp-api.hoangha.shop"               # google-search-results

curl "https://serp-api.hoangha.shop/search?engine=google&q=coffee&gl=vn&api_key=sk_live_..."

Endpoints: /search, /searches/{id}, /account, /locations.json. See the migration guide for the four behaviour differences.

The output query parameter on the fetch endpoint controls the response shape:

There is no bespoke SDK to install — the API is plain JSON over HTTPS, so any language with an HTTP client works. The service publishes a live OpenAPI 3.1 schema you can explore interactively or feed to a client generator for a typed SDK.

# TypeScript types from the live schema
npx openapi-typescript https://serp-api.hoangha.shop/openapi.json -o serp-api.d.ts

# or a full client in any language (Go, Java, PHP, Ruby, Rust, C#, …)
openapi-generator-cli generate -i https://serp-api.hoangha.shop/openapi.json -g python -o ./serp-api-client

Ready-to-paste submit-and-poll snippets for Node, Python, PHP, Go, and Ruby live in the Language SDKs guide.

The Model Context Protocol server exposes the SERP API to AI agents (Claude, IDEs, and other MCP clients) as callable tools. It talks to a running SERP API over the same /v1 surface, so point it at the hosted service or a local instance.

Install & run

pip install -e '.[mcp]'                 # optional dep group
export SERP_API_BASE_URL=https://serp-api.hoangha.shop
export SERP_API_KEY=sk_live_...

serp-api-mcp                            # stdio transport
# or: python -m serp_api.mcp_server

Tools

Connect Claude Desktop

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "serp-api": {
      "command": "serp-api-mcp",
      "env": {
        "SERP_API_BASE_URL": "https://serp-api.hoangha.shop",
        "SERP_API_KEY": "sk_live_..."
      }
    }
  }
}

Following the llms.txt convention, we publish a machine-readable index so LLMs and agents can discover the product and API quickly.

What each file contains and how to wire it into Cursor, Windsurf, Claude, or ChatGPT is on the AI docs page.