Uma linha para o Claude Code, o mesmo bloco stdio para todos os outros clientes — comando uvx, argumento serphubapi-mcp, sua chave no ambiente.

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

A instalação é só isso: seu agente ganha list_services, search, batch e fetch. O servidor precisa do uv instalado (ele fornece o uvx) e se comunica com 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" }
    }
  }
}

Ferramentas e preços: list_services é grátis; search custa o preço do serviço (ex.: google/web 10 créditos, cache_first metade, 0 em acerto de cache) mais 3 por página de conteúdo; fetch custa 5 créditos por página, 0 em caso de falha; batch cobra cada item como uma busca. Referência completa: Documentação do MCP →

Skill: para agentes que chamam a API diretamente

Se o seu agente chama HTTP diretamente em vez de usar MCP, entregue a ele o SKILL.md da raiz do repositório. Ele explica quando buscar, quando pedir uma resposta com citações, quando extrair uma página e como fazer buscas em lote.

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

Os mesmos endpoints, sem MCP: POST /v1/search, POST /v1/ai-search, POST /v1/fetch e POST /v1/batch, todos com o header X-API-Key.

Se as ferramentas não aparecerem

• Rode uvx serphubapi-mcp em um terminal: se ele iniciar, o pacote está ok e o problema é a configuração do cliente.
• Confira a chave: ela começa com shapi_ (chaves antigas começam com fapi_ e continuam funcionando).
• Reinicie o cliente depois de editar a configuração e acompanhe seus gastos em /dashboard/logs.

Não precisa de agente. Toda chamada é um POST com sua chave no header X-API-Key; chamadas com falha, vazias ou com acerto de cache são grátis. Referência completa: Documentação da API →

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"])

Outros endpoints com a mesma chave: POST /v1/ai-search para uma resposta com citações, POST /v1/fetch para transformar uma página em Markdown, POST /v1/batch para até 5 buscas em uma chamada.

Cadastre-se e teste sem configurar nada: entre e faça buscas no Playground do console, cobradas pela tarifa padrão. Contas novas ganham 1.000 créditos grátis.

Abrir o Playground →

Para pipelines de dados e comparações: até 5 buscas independentes em uma chamada. Cada item é cobrado como uma busca individual, e a falha de um item não bloqueia os demais.

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"}]}'

A resposta sempre retorna JSON, com resultados por item e meta.total_credits_charged para a chamada inteira.