Resposta rápida
Como adiciono um servidor MCP de pesquisa na web ao Claude Code ou ao Claude Desktop?
Salve o servidor Python curto desta página, que expõe as ferramentas search_web e read_urls chamando LLMWebSearch, depois registre-o com claude mcp add ou no claude_desktop_config.json, com a sua chave em env. O modelo então pode pesquisar na web ao vivo e ler as principais páginas como Markdown. Uma pesquisa custa 1 crédito, a partir de US$ 1,20/1K pesquisas em outubro de 2026. Sem KYC; pague com cripto.
O servidor MCP em resumo
| Linguagem | Python 3.10+, com os pacotes mcp e httpx |
|---|---|
| Transporte | stdio: o cliente inicia o servidor como um processo local |
| Ferramenta 1 | search_web(query, max_results=5, read=3) → fontes numeradas com URLs e texto da página |
| Ferramenta 2 | read_urls(urls) → o conteúdo principal de 1 a 20 páginas conhecidas |
| Nomes | Não web_search nem web_fetch: Claude Code e OpenClaw já trazem ferramentas com esses nomes |
| Chave | Leia de LLMWEBSEARCH_API_KEY no ambiente do servidor |
| Cobrança | Um crédito paga uma pesquisa: até 20 resultados classificados, com as páginas dos 3 primeiros lidas e devolvidas em Markdown. Ler de 4 a 10 páginas custa 2 créditos. Uma chamada que termina em erro não custa nada. Ler páginas cujas URLs você já tem custa 1 crédito por cada grupo iniciado de 3 páginas devolvidas com conteúdo, até 20 URLs por chamada; URLs recusadas ou com falha não são contadas |
Por que as ferramentas se chamam search_web e read_urls?
Porque duas ferramentas com o mesmo nome confundem o cliente e o modelo. Claude Code e OpenClaw incluem cada um ferramentas nativas chamadas web_search e web_fetch. Nomes distintos, com descrições claras, permitem que o modelo escolha as nossas de propósito e que você distinga as chamadas nos logs.
As duas ferramentas retornam texto, não JSON bruto. Cada fonte começa com um número, um título e a sua URL, para que o modelo possa citar [1] ou [2] e o leitor possa conferir a página.
import os
import httpx
from mcp.server.fastmcp import FastMCP
BASE = "https://llmwebsearch.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
mcp = FastMCP("llmwebsearch")
def _call(path: str, body: dict) -> dict:
resp = httpx.post(BASE + path, json=body, headers=HEADERS, timeout=90)
data = resp.json()
if resp.status_code != 200:
err = data.get("error", {})
raise RuntimeError(err.get("code", str(resp.status_code)) + ": " + err.get("message", ""))
return data
def _page(n: int, item: dict) -> str:
head = f"[{n}] {item.get('title') or item['url']}\n{item['url']}\n"
if item.get("content_status") == "ok":
return head + item["content"]
return head + "(not read: " + item.get("content_status", "unknown") + ") " + item.get("snippet", "")
@mcp.tool()
def search_web(query: str, max_results: int = 5, read: int = 3) -> str:
"""Search the live web and return numbered sources; the first `read` pages include their text.
Use it for current facts, documentation and news. Cite sources by their number.
"""
body = {"q": query, "max_results": max(1, min(max_results, 20)), "read": max(0, min(read, 10)), "max_chars": 5000}
data = _call("/search", body)
return "\n\n".join(_page(i, r) for i, r in enumerate(data["results"], start=1))
@mcp.tool()
def read_urls(urls: list[str]) -> str:
"""Read 1 to 20 public web pages whose URLs you already have and return their main text."""
data = _call("/extract", {"urls": urls[:20], "max_chars": 12000})
return "\n\n".join(_page(i, r) for i, r in enumerate(data["results"], start=1))
if __name__ == "__main__":
mcp.run()
Como instalo e testo o servidor?
Crie um ambiente virtual, instale mcp e httpx e salve o arquivo acima. O mcp é o SDK oficial do Python do Model Context Protocol; a sua classe FastMCP transforma funções Python tipadas em ferramentas e usa cada docstring como a descrição da ferramenta.
Inicie o arquivo uma vez a partir de um terminal com a sua chave definida. Ele então fica aguardando em silêncio um cliente na entrada padrão, o que significa que funciona; pare-o com Ctrl+C. Erros da API são lançados como erros de ferramenta com o seu código, para que o modelo veja rate_limited ou insufficient_credits em palavras simples.
python -m venv .venv
. .venv/bin/activate
pip install "mcp[cli]" httpx
LLMWEBSEARCH_API_KEY="your-key" python llmwebsearch_mcp.pyComo adiciono ao Claude Code?
Use claude mcp add. A documentação do Claude Code mostra o formato claude mcp add [options] <name> -- <command> [args...]: primeiro as opções próprias dele, depois um duplo traço, depois o comando que inicia o servidor. Variáveis de ambiente vão em --env KEY=value, e pelo menos uma outra opção, como --transport stdio, precisa ficar entre --env e o nome do servidor.
Adicione --scope user para disponibilizar o servidor em todos os seus projetos; o escopo padrão, local, cobre apenas o projeto atual. Use caminhos absolutos para o Python do seu ambiente virtual e para o arquivo do servidor.
claude mcp add --env LLMWEBSEARCH_API_KEY=your-key --transport stdio --scope user llmwebsearch \
-- /home/you/llmwebsearch/.venv/bin/python /home/you/llmwebsearch/llmwebsearch_mcp.pyComo adiciono ao Claude Desktop e a outros clientes?
O Claude Desktop lê servidores de claude_desktop_config.json, em mcpServers. Dê um nome ao servidor, o comando, seus argumentos e um objeto env com a chave, depois reinicie o app; search_web e read_urls aparecem na lista de tools.
Outros clientes MCP, como o Cursor, pedem as mesmas três coisas nas próprias configurações de MCP: um comando, seus argumentos e variáveis de ambiente. A chave nunca aparece em um argumento de tool nem na conversa.
{
"mcpServers": {
"llmwebsearch": {
"command": "/home/you/llmwebsearch/.venv/bin/python",
"args": ["/home/you/llmwebsearch/llmwebsearch_mcp.py"],
"env": { "LLMWEBSEARCH_API_KEY": "your-key" }
}
}
}Como mantenho as pesquisas baratas e curtas?
Diga ao modelo como pesquisar nas suas instruções: uma ou duas pesquisas por pergunta, depois leia mais só se as fontes divergirem. O servidor já limita cada página a 5.000 caracteres em search_web e 12.000 em read_urls; reduza esses números para modelos pequenos.
Cada chamada de search_web com read até 3 é um crédito. Um assistente que faz 40 pesquisas por dia usa cerca de 1.200 créditos por mês, então 5.000 pesquisas (US$ 9,25) dura cerca de quatro meses. Os créditos de pesquisa não têm data de expiração: o que você não usar este mês continua lá no ano que vem.
O que o modelo vê quando uma página não pode ser lida?
A fonte ainda aparece, com seu número, título e URL, seguida do motivo entre colchetes e do snippet da pesquisa. Nosso leitor respeita o robots.txt: ele se identifica como LLMWebSearch, segue as regras que um site escreve para ele ou para todos os robôs e deixa de fora o conteúdo de qualquer página que não tem permissão para ler. Quando um site recusa o nosso leitor, o resultado volta sem conteúdo e com o status do site: nunca resolvemos CAPTCHAs, não entramos em contas nem contornamos um bloqueio ou um paywall. O modelo pode então contar com as outras fontes ou dizer que uma página não estava disponível.
Servidor MCP: perguntas frequentes
Existe um pacote MCP oficial do LLMWebSearch ou um endpoint hospedado?
Não. O arquivo desta página é a integração: cerca de 50 linhas que você pode ler e alterar. Ele roda na sua máquina, e sua chave só vai para a nossa API.
Devo desativar a pesquisa web nativa do Claude Code?
Não precisa. As duas podem ficar; as descrições dizem ao modelo o que cada uma faz. Mantenha a nossa quando quiser o texto da página nos resultados, um preço fixo por pesquisa ou um lugar único para seus logs de pesquisa.
Posso usá-lo com o OpenClaw?
Sim, como um servidor MCP registrado com openclaw mcp add. A página do OpenClaw traz o comando e explica como ele fica ao lado dos provedores de pesquisa nativos do OpenClaw.
O servidor guarda minhas pesquisas?
Não. Ele não guarda nada entre chamadas. Do nosso lado, Não treinamos nenhum modelo com as suas consultas ou com o que a API retorna, e não adicionamos nenhuma regra própria contra armazenar resultados; os direitos dos sites cujas páginas você lê continuam valendo.
Fontes (1)
- Conectar o Claude Code a ferramentas via MCP — Claude Code docs (read 2026-10-22)