Creare un server MCP in Python per collegare Claude ai tuoi dati

Un modello come Claude, da solo, sa solo conversare: non può leggere i tuoi file, interrogare un database aziendale o chiamare un'API interna. Il Model Context Protocol (MCP), lo standard aperto introdotto da Anthropic e oggi adottato da numerosi strumenti, serve esattamente a colmare questo vuoto. È una sorta di «presa universale» tra i modelli di IA e il mondo esterno: scrivi una volta un piccolo «server» che espone dati e strumenti, e qualunque client compatibile — Claude Desktop, Claude Code, vari IDE — può usarlo. In questa guida costruiremo da zero un server MCP in Python e lo collegheremo a Claude.

A chi serve questa guida e cosa otterrai

È un tutorial di livello intermedio-avanzato, pensato per chi sa già muoversi con Python e la riga di comando e vuole dare a un assistente IA capacità concrete sui propri dati. Al termine avrai un server MCP funzionante che espone due «strumenti» (la ricerca in una cartella di documenti e il calcolo di statistiche) e una «risorsa», e lo userai direttamente dentro Claude Desktop. Da lì potrai estenderlo a database, CRM, API meteo, fogli di calcolo: la logica resta la stessa.

Prerequisiti reali: Python 3.10 o superiore, un sistema Windows, macOS o Linux, l'app Claude Desktop installata (gratuita, disponibile per Windows e Mac) e dimestichezza con il terminale. Non serve una GPU né un account a pagamento per la parte di sviluppo del server.

Quale strumento usare: SDK ufficiale e FastMCP

Per il linguaggio Python esiste l'SDK ufficiale del protocollo, che include FastMCP, un'interfaccia ad alto livello che riduce drasticamente il codice da scrivere: si definiscono gli strumenti come normali funzioni Python decorate, e la libreria gestisce in automatico la comunicazione. È la prima scelta consigliata perché ufficiale, ben documentata e adottata dalla comunità. In alternativa esistono SDK per TypeScript/Node, Java, Kotlin e C#: se il tuo ecosistema è diverso da Python il protocollo è lo stesso, cambia solo la libreria.

Passo 1 — Preparare l'ambiente

Crea una cartella per il progetto e un ambiente virtuale, poi installa l'SDK:

mkdir mcp-server-demo && cd mcp-server-demo
python -m venv .venv
# Attiva l'ambiente: su macOS/Linux
source .venv/bin/activate
# su Windows (PowerShell)
.venv\Scripts\Activate.ps1

pip install "mcp[cli]"

Il pacchetto mcp[cli] installa sia la libreria sia lo strumento da riga di comando che useremo per testare e installare il server.

Passo 2 — Scrivere il server

Crea un file server.py. Definiamo un server, due strumenti (uno che cerca testo nei file .txt di una cartella, uno che calcola media e somma di una lista di numeri) e una risorsa che restituisce informazioni di sistema.

from mcp.server.fastmcp import FastMCP
from pathlib import Path
import statistics

mcp = FastMCP("Assistente Dati Locale")

DOCS = Path.home() / "Documenti"  # cartella da indicizzare

@mcp.tool()
def cerca_nei_documenti(parola: str) -> str:
    """Cerca una parola nei file .txt della cartella Documenti e
    restituisce i nomi dei file con la riga corrispondente."""
    risultati = []
    for f in DOCS.glob("*.txt"):
        for i, riga in enumerate(f.read_text(encoding="utf-8", errors="ignore").splitlines(), 1):
            if parola.lower() in riga.lower():
                risultati.append(f"{f.name} (riga {i}): {riga.strip()}")
    return "\n".join(risultati) if risultati else "Nessun risultato."

@mcp.tool()
def statistiche(numeri: list[float]) -> dict:
    """Calcola somma, media e mediana di una lista di numeri."""
    return {
        "somma": sum(numeri),
        "media": statistics.mean(numeri),
        "mediana": statistics.median(numeri),
    }

@mcp.resource("info://sistema")
def info_sistema() -> str:
    """Restituisce la cartella attualmente indicizzata."""
    return f"Cartella documenti: {DOCS}"

if __name__ == "__main__":
    mcp.run()  # trasporto stdio, il piu' usato dai client desktop

Tre punti chiave: il decoratore @mcp.tool() trasforma una funzione in uno strumento invocabile dal modello; la docstring è fondamentale, perché è la descrizione che Claude legge per capire quando e come usare lo strumento; i tipi degli argomenti (str, list[float]) generano automaticamente lo schema dei parametri.

Passo 3 — Testare il server prima di collegarlo

Prima di agganciarlo a Claude, verifica che funzioni con l'ispettore incluso nell'SDK, che apre un'interfaccia web per provare strumenti e risorse:

mcp dev server.py

Si aprirà l'MCP Inspector nel browser: seleziona la scheda «Tools», prova statistiche con un input come [10, 20, 30] e controlla che restituisca media 20. Se qui tutto risponde, il problema in fase di integrazione sarà nella configurazione, non nel codice.

Passo 4 — Collegarlo a Claude Desktop

Il modo più semplice è il comando di installazione automatica, che registra il server nel file di configurazione di Claude Desktop:

mcp install server.py

In alternativa puoi modificare a mano il file di configurazione. Su macOS si trova in ~/Library/Application Support/Claude/claude_desktop_config.json, su Windows in %APPDATA%\Claude\claude_desktop_config.json. Aggiungi il tuo server alla sezione mcpServers:

{
  "mcpServers": {
    "assistente-dati": {
      "command": "/percorso/assoluto/.venv/bin/python",
      "args": ["/percorso/assoluto/mcp-server-demo/server.py"]
    }
  }
}

Usa sempre percorsi assoluti, sia per l'interprete Python sia per lo script. Salva, chiudi completamente Claude Desktop e riaprilo: comparirà l'icona degli strumenti MCP. Ora puoi scrivere a Claude un prompt come questo:

Cerca la parola "fattura" nei miei documenti e poi calcola la media degli importi 1200, 980 e 1450.

Claude riconoscerà di dover invocare prima cerca_nei_documenti e poi statistiche, ti chiederà conferma per eseguirli e integrerà i risultati nella risposta. È il comportamento agentico: il modello sceglie da solo quali strumenti usare e in che ordine.

Varianti e casi avanzati

Da questa base puoi crescere in molte direzioni. Per interrogare un database, scrivi uno strumento che apre una connessione (per esempio con sqlite3 o psycopg) ed esegue query parametrizzate. Per esporre file come contesto, usa le resource invece dei tool: il client può precaricarle senza una chiamata esplicita. Se ti serve raggiungere il server da remoto o da più client web, FastMCP supporta anche il trasporto HTTP con eventi server-sent al posto di stdio. E puoi usare lo stesso server con Claude Code registrandolo via claude mcp add, oppure con qualunque altro client compatibile con il protocollo.

Errori comuni e come risolverli

• «Server disconnected» o il server non appare in Claude: quasi sempre è un percorso sbagliato nel file di configurazione. Verifica che command punti all'interprete dell'ambiente virtuale (non al Python di sistema) e usa percorsi assoluti.
• «spawn python ENOENT»: Claude non trova l'eseguibile. Indica il percorso completo dell'interprete, ad esempio quello dentro .venv.
• Lo strumento c'è ma Claude non lo usa: migliora la docstring. Se la descrizione è vaga, il modello non capisce quando invocarlo; scrivila come se spiegassi a un collega cosa fa la funzione e quando serve.
• Modifiche al codice ignorate: Claude Desktop carica il server all'avvio. Dopo ogni modifica chiudi e riapri l'app, non basta salvare il file.
• Errori di codifica leggendo i file: aggiungi errors="ignore" o specifica l'encoding corretto, come nell'esempio.

Quando NON usare un server MCP

MCP è potente ma non sempre necessario. Se ti serve solo incollare un documento in chat o fare una domanda secca, l'allegato diretto in Claude è più rapido. Se devi costruire un servizio web ad alto traffico con logica complessa, una normale API REST con il tuo backend resta più adatta. MCP dà il meglio quando vuoi che un assistente conversazionale acceda in modo strutturato, ripetibile e sicuro a strumenti e dati locali. Il prossimo passo naturale è trasformare i tuoi strumenti interni — script, query, integrazioni — in altrettanti server MCP, costruendo a poco a poco un assistente che conosce davvero il tuo lavoro.