Servidor MCP do Google Search para Claude Desktop, Cursor e outros clientes MCP

O que o servidor faz?

Ele expõe uma ferramenta, google_search, por meio do Model Context Protocol. Quando o modelo a chama, o servidor envia uma requisição para https://serpcrypto.com/api/v1/search e transforma o JSON em texto simples e curto: o AI Overview, se o Google exibiu um, e os principais resultados com título, link e snippet.

Texto curto importa. Uma página de resultados completa em JSON é longa, e cada caractere enviado de volta ao modelo consome contexto. O servidor mantém até dez resultados e corta o overview em 800 caracteres; altere esses limites no código se seu cliente tiver espaço para mais.

Este é um código para copiar e colar, não um pacote publicado: não há pacote MCP oficial do SerpCrypto para instalar. O arquivo é seu e você pode adicionar ferramentas, por exemplo uma para engine=google_news.

"""serpcrypto_mcp.py: an MCP server that gives AI clients a Google search tool.

Install once:  pip install "mcp[cli]" httpx
Run by your MCP client over stdio; the API key comes from the environment.
"""
import os

import httpx
from mcp.server.fastmcp import FastMCP

API_URL = "https://serpcrypto.com/api/v1/search"
mcp = FastMCP("serpcrypto-search")


@mcp.tool()
async def google_search(query: str, gl: str = "us", hl: str = "en", num_results: int = 5) -> str:
    """Search Google and return the top results (title, link, snippet) and the AI Overview text if any.

    gl is a two-letter country code (us, gb, de...), hl a language code (en, de, pt-BR...).
    Each call uses one SerpCrypto search credit.
    """
    headers = {"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]}
    params = {"q": query, "gl": gl, "hl": hl}
    async with httpx.AsyncClient(timeout=90) as client:
        r = await client.get(API_URL, params=params, headers=headers)
    if r.status_code != 200:
        return f"Search failed with HTTP {r.status_code}: {r.text[:300]}"
    data = r.json()
    lines = []
    overview = data.get("ai_overview") or {}
    if overview.get("text"):
        lines.append("AI Overview: " + overview["text"][:800])
    for item in data.get("organic_results", [])[: max(1, min(num_results, 10))]:
        lines.append(f"{item['position']}. {item['title']}\n{item['link']}\n{item.get('snippet', '')}")
    return "\n\n".join(lines) or "No results."


if __name__ == "__main__":
    mcp.run()  # stdio transport

Por que a ferramenta se chama google_search e não web_search?

Vários clientes já trazem uma ferramenta chamada web_search que usa o próprio provedor deles. Um nome distinto evita conflito e mostra ao modelo o que ele recebe: resultados do Google para um país e um idioma que ele escolhe. A docstring é a descrição que o modelo lê, por isso ela informa os parâmetros e o custo de uma chamada.

Como adiciono ao Claude Desktop?

Abra o arquivo de configuração, claude_desktop_config.json: no macOS ele fica em ~/Library/Application Support/Claude/, no Windows em %APPDATA%\Claude\. Adicione o servidor em mcpServers, com o caminho absoluto para o script e sua chave em env, depois reinicie o Claude Desktop.

Se python não estiver no path que o Claude Desktop enxerga, use o caminho completo para o interpretador, por exemplo o que está dentro do seu ambiente virtual.

{
  "mcpServers": {
    "serpcrypto-search": {
      "command": "python",
      "args": ["/absolute/path/to/serpcrypto_mcp.py"],
      "env": {
        "SERPCRYPTO_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Como adiciono ao Claude Code e ao Cursor?

No Claude Code, registre-o a partir de um terminal com claude mcp add; -e define a variável de ambiente e tudo depois de -- é o comando a executar. No Cursor, coloque o mesmo bloco mcpServers acima em ~/.cursor/mcp.json para cada projeto, ou em .cursor/mcp.json dentro de um projeto.

Outros clientes MCP que iniciam servidores stdio recebem as mesmas três coisas: um comando, os seus argumentos e variáveis de ambiente. A página do OpenClaw mostra os comandos para o OpenClaw.

claude mcp add serpcrypto-search \
  -e SERPCRYPTO_API_KEY=paste-your-key-here \
  -- python /absolute/path/to/serpcrypto_mcp.py

Como mantenho a chave de API segura?

Guarde-a no bloco env da configuração do cliente ou no seu perfil de shell, nunca dentro de serpcrypto_mcp.py. Assim o script pode ser partilhado ou submetido sem a chave. Se uma chave for exposta, revogue-a no dashboard e crie uma nova: Chaves de API que você pode criar e revogar a qualquer momento no seu painel.

Dê ao servidor MCP a sua própria chave. O uso por chave mostra então quantas pesquisas o assistente faz, separado dos seus scripts.

Quantos créditos um assistente vai usar?

Um por cada chamada de ferramenta bem-sucedida. Um chat em que o modelo pesquisa três vezes custa três créditos. No pack 25.000 pesquisas a partir de US$ 18,75, isso são milhares de perguntas assistidas, e Os créditos de pesquisa pré-pagos nunca expiram: as pesquisas não utilizadas ficam na sua conta até você usá-las.

Para limitar o uso, reduza num_results (não altera o preço, mas encurta as respostas) e indique ao modelo nas suas instruções para pesquisar só quando precisar de factos recentes.