One line for Claude Code, the same stdio block for every other client — command uvx, argument serphubapi-mcp, your key in the environment.

claude mcp add serphubapi -e SERPHUBAPI_API_KEY=shapi_xxxxxxxx -- uvx serphubapi-mcp

That is the whole install: your agent gets list_services, search, batch and fetch. The server needs uv installed (it provides uvx) and talks to https://api.serphubapi.com.

{
  "mcpServers": {
    "serphubapi": {
      "command": "uvx",
      "args": ["serphubapi-mcp"],
      "env": { "SERPHUBAPI_API_KEY": "shapi_xxxxxxxx" }
    }
  }
}

{
  "servers": {
    "serphubapi": {
      "command": "uvx",
      "args": ["serphubapi-mcp"],
      "env": { "SERPHUBAPI_API_KEY": "shapi_xxxxxxxx" }
    }
  }
}

{
  "mcpServers": {
    "serphubapi": {
      "command": "uvx",
      "args": ["serphubapi-mcp"],
      "env": { "SERPHUBAPI_API_KEY": "shapi_xxxxxxxx" }
    }
  }
}

{
  "mcpServers": {
    "serphubapi": {
      "command": "uvx",
      "args": ["serphubapi-mcp"],
      "env": { "SERPHUBAPI_API_KEY": "shapi_xxxxxxxx" }
    }
  }
}

{
  "mcp": {
    "serphubapi": {
      "type": "local",
      "command": ["uvx", "serphubapi-mcp"],
      "environment": { "SERPHUBAPI_API_KEY": "shapi_xxxxxxxx" }
    }
  }
}

Tools and prices: list_services is free; search costs the service's price (e.g. google/web 10 credits, cache_first half, 0 on a cache hit) plus 3 per page of content; fetch is 3 credits a page, 0 on failure; batch bills each item like a search. Full reference: MCP docs →

Skill: for agents that call the API directly

If your agent calls HTTP itself instead of using MCP, give it the SKILL.md from the repository root. It covers when to search, when to ask for an answer with citations, when to fetch a page, and how to batch searches.

# In your agent's skills folder, or pasted into its instructions:
# https://github.com/sou2026x/serp/blob/main/SKILL.md

The same endpoints, without MCP: POST /v1/search, POST /v1/ai-search, POST /v1/fetch and POST /v1/batch, all with the X-API-Key header.

If the tools do not appear

• Run uvx serphubapi-mcp in a terminal: if it starts, the package is fine and the problem is the client config.
• Check the key: it starts with shapi_ (older keys start with fapi_ and still work).
• Restart the client after editing its config, and check your spend at /dashboard/logs.

No agent needed. Every call is one POST with your key in the X-API-Key header; failed, empty and cache-hit calls are free. Full reference: API docs →

curl -s https://api.serphubapi.com/v1/search \
  -H "X-API-Key: shapi_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"q": "best espresso machine 2026", "engine": "google", "num": 5}'

import json, urllib.request

req = urllib.request.Request(
    "https://api.serphubapi.com/v1/search",
    data=json.dumps({"q": "best espresso machine 2026", "engine": "google", "num": 5}).encode(),
    headers={"X-API-Key": "shapi_xxxxxxxx", "Content-Type": "application/json"},
)
with urllib.request.urlopen(req) as r:
    print(json.load(r)["results"])

Other endpoints on the same key: POST /v1/ai-search for an answer with citations, POST /v1/fetch to turn a page into Markdown, POST /v1/batch for up to 5 searches in one call.

No setup at all: sign in and try searches in the console Playground, billed at the standard rate. New accounts get 1,000 free credits.

Open the Playground →

For data pipelines and comparisons: up to 5 independent searches in one call. Each item bills like a single search, and one item failing does not block the others.

curl -s https://api.serphubapi.com/v1/batch \
  -H "X-API-Key: shapi_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"q": "espresso", "engine": "google"}, {"q": "espresso", "engine": "xiaohongshu", "type": "notes"}]}'

The response always returns JSON, with per-item results and meta.total_credits_charged for the whole call.