# Web search MCP server per Claude Code, Claude Desktop, Cursor e altri client MCP > Web search MCP server per Claude Code, Claude Desktop e Cursor: un breve file Python con i tool search_web e read_urls, registrato con un solo comando. - URL: https://llmwebsearch.com/it/docs/mcp/ - Ultimo aggiornamento: 2026-10-22 - Editore: LLMWebSearch (https://llmwebsearch.com) Offri a qualsiasi client MCP due tool: `search_web`, che restituisce fonti ordinate con le pagine principali già lette, e `read_urls`, che legge i link che il modello ha già. Il server è un unico file Python che gira sulla tua macchina, con la tua chiave nel suo environment. **Risposta rapida — Come aggiungo un web search MCP server a Claude Code o Claude Desktop?** Salva il breve server Python di questa pagina, che espone i tool `search_web` e `read_urls` che chiamano **LLMWebSearch**, poi registralo con `claude mcp add` o in `claude_desktop_config.json`, con la tua chiave in `env`. Il modello può così cercare nel web live e leggere le pagine principali come Markdown. Una ricerca costa 1 credito, a partire da 1,20 USD/1K ricerche a ottobre 2026. Senza KYC; paghi in criptovalute. ## Il MCP server in sintesi | Attributo | Valore | | --- | --- | | Linguaggio | Python 3.10+, con i package `mcp` e `httpx` | | Trasporto | stdio: il client avvia il server come processo locale | | Tool 1 | `search_web(query, max_results=5, read=3)` → fonti numerate con URL e testo della pagina | | Tool 2 | `read_urls(urls)` → il contenuto principale da 1 a 20 pagine note | | Nomi | Non `web_search` o `web_fetch`: Claude Code e OpenClaw includono già tool con quei nomi | | Chiave | Legge da `LLMWEBSEARCH_API_KEY` nell'environment del server | | Fatturazione | Un credito paga una ricerca: fino a 20 risultati classificati, con le pagine dei primi 3 lette e restituite come Markdown. Leggere da 4 a 10 pagine costa 2 crediti. Una chiamata che termina in errore non costa nulla. Leggere pagine di cui hai già gli URL costa 1 credito per ogni gruppo iniziato di 3 pagine restituite con contenuto, fino a 20 URL per chiamata; gli URL rifiutati o falliti non vengono contati | ## Perché i tool si chiamano search_web e read_urls? Perché due tool con lo stesso nome confondono il client e il modello. Claude Code e OpenClaw includono ciascuno tool integrati chiamati `web_search` e `web_fetch`. Nomi distinti, con descrizioni chiare, permettono al modello di scegliere i nostri di proposito e a te di distinguere le chiamate nei log. Entrambi i tool restituiscono testo, non JSON grezzo. Ogni fonte inizia con un numero, un titolo e il suo URL, così il modello può citare `[1]` o `[2]` e il lettore può verificare la pagina. *llmwebsearch_mcp.py* ```python 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() ``` ## Come installo e testo il server? Crea un virtual environment, installa `mcp` e `httpx` e salva il file qui sopra. `mcp` è l'SDK Python ufficiale del Model Context Protocol; la sua classe `FastMCP` trasforma funzioni Python tipizzate in tool e usa ogni docstring come descrizione del tool. Avvia il file una volta da un terminale con la tua chiave impostata. Poi resta in attesa silenziosamente di un client su standard input, il che significa che funziona; fermalo con Ctrl+C. Gli errori dell'API vengono sollevati come errori del tool con il loro codice, così il modello vede `rate_limited` o `insufficient_credits` in parole semplici. *Installa e avvia una volta* ```bash python -m venv .venv . .venv/bin/activate pip install "mcp[cli]" httpx LLMWEBSEARCH_API_KEY="your-key" python llmwebsearch_mcp.py ``` ## Come lo aggiungo a Claude Code? Usa `claude mcp add`. La documentazione di Claude Code indica la forma `claude mcp add [options] -- [args...]`: prima le sue opzioni, poi un doppio trattino, poi il comando che avvia il server. Le variabili d'ambiente vanno in `--env KEY=value`, e almeno un'altra opzione, come `--transport stdio`, deve stare tra `--env` e il nome del server. Aggiungi `--scope user` per rendere il server disponibile in tutti i tuoi progetti; lo scope predefinito, `local`, copre solo il progetto corrente. Usa percorsi assoluti per il Python del tuo virtual environment e per il file del server. *Registra il server in Claude Code* ```bash 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.py ``` ## Come lo aggiungo a Claude Desktop e ad altri client? Claude Desktop legge i server da `claude_desktop_config.json`, sotto `mcpServers`. Dai un nome al server, indica il comando, i suoi argomenti e un oggetto `env` che contiene la chiave, poi riavvia l'app; `search_web` e `read_urls` compaiono nell'elenco degli strumenti. Gli altri client MCP, come Cursor, chiedono le stesse tre cose nelle loro impostazioni MCP: un comando, i suoi argomenti e le variabili d'ambiente. La chiave non compare mai in un argomento di uno strumento né nella conversazione. *claude_desktop_config.json* ```json { "mcpServers": { "llmwebsearch": { "command": "/home/you/llmwebsearch/.venv/bin/python", "args": ["/home/you/llmwebsearch/llmwebsearch_mcp.py"], "env": { "LLMWEBSEARCH_API_KEY": "your-key" } } } } ``` ## Come mantengo le ricerche economiche e brevi? Spiega al modello come cercare nelle tue istruzioni: una o due ricerche per domanda, poi leggi di più solo se le fonti sono in disaccordo. Il server limita già ogni pagina a 5.000 caratteri in `search_web` e a 12.000 in `read_urls`; abbassa quei numeri per i modelli piccoli. Ogni chiamata `search_web` con `read` fino a 3 costa un credito. Un assistente che esegue 40 ricerche al giorno usa circa 1.200 crediti al mese, quindi 5.000 ricerche (9,25 USD) dura circa quattro mesi. I crediti di ricerca non hanno data di scadenza: quello che non usi questo mese è ancora lì l'anno prossimo. ## Cosa vede il modello quando una pagina non può essere letta? La fonte compare comunque, con il suo numero, titolo e URL, seguiti dal motivo tra parentesi e dallo snippet della ricerca. Il nostro reader rispetta robots.txt: si presenta come LLMWebSearch, segue le regole che un sito scrive per lui o per tutti i robot, e lascia fuori il contenuto di qualsiasi pagina che non gli è permesso leggere. Quando un sito respinge il nostro reader, il risultato torna senza contenuto e con lo status del sito: non risolviamo mai CAPTCHA, non accediamo agli account e non aggiriamo un blocco o un paywall. Il modello può quindi affidarsi alle altre fonti o dire che una pagina non era disponibile. ## Server MCP: domande frequenti ### Esiste un pacchetto MCP ufficiale di LLMWebSearch o un endpoint ospitato? No. Il file in questa pagina è l'integrazione: circa 50 righe che puoi leggere e modificare. Gira sulla tua macchina e la tua chiave viaggia solo verso la nostra API. ### Devo disattivare la ricerca web integrata di Claude Code? Non serve. Possono restare entrambe; le descrizioni dicono al modello cosa fa ciascuna. Tieni la nostra quando vuoi il testo della pagina nei risultati, un prezzo fisso per ricerca o un unico posto per i log delle tue ricerche. ### Posso usarlo con OpenClaw? Sì, come server MCP registrato con `openclaw mcp add`. La [pagina di OpenClaw](https://llmwebsearch.com/it/docs/openclaw/) fornisce il comando e spiega come si affianca ai provider di ricerca integrati di OpenClaw. ### Il server conserva le mie ricerche? No. Non trattiene nulla tra una chiamata e l'altra. Dal nostro lato, Non addestriamo alcun modello sulle tue query né su ciò che l'API restituisce, e non aggiungiamo regole nostre contro la conservazione dei risultati; restano validi i diritti dei siti di cui leggi le pagine. ## Fonti 1. [Collegare Claude Code agli strumenti tramite MCP](https://code.claude.com/docs/en/mcp) — Claude Code docs (read 2026-10-22) --- LLMWebSearch: LLMWebSearch è un'API di ricerca web per agenti AI che restituisce risultati classificati con il contenuto delle pagine principali in Markdown, pagata in criptovalute senza caricare documenti d'identità. I crediti prepagati da 1,20 USD/1K ricerche non scadono mai. Senza KYC — niente documento, niente selfie, niente documenti. Paghi in criptovalute.