Costruire un server MCP in Python da zero

Il Model Context Protocol (MCP) è ormai uno standard del settore. Ha raggiunto i 97 milioni di download mensili degli SDK. Ogni importante strumento di IA lo utilizza. La maggior parte delle guide mostra solo come installare server esistenti. Questa guida ti mostra come costruirne uno tuo utilizzando Python e l'API di GitHub.

Cos'è MCP? È un protocollo che consente ai client IA di chiamare servizi esterni. Il tuo server gestisce le richieste da strumenti come Claude o Cursor.

Le tre parti fondamentali di MCP:

  • Tool: Funzioni che l'IA chiama per compiere azioni o ottenere dati.
  • Resource: Endpoint di dati in sola lettura, come file o record di database.
  • Prompt: Template di istruzioni riutilizzabili per workflow coerenti.

Configura il tuo progetto Crea una directory e installa le librerie necessarie utilizzando uv:

mkdir github-mcp-server
cd github-mcp-server
uv init .
uv add "mcp[cli]" httpx

Costruire il server Usa FastMCP per gestire la parte più complessa. Un buon server MCP utilizza tre file specifici: server.py, pyproject.toml e un file .env opzionale per il tuo token GitHub.

Consigli professionali per lo sviluppo:

  • Usa i modelli Pydantic per i ritorni dei tool. Questo fornisce all'IA dati strutturati invece di stringhe disordinate.
  • Scrivi docstring chiare. L'IA le legge per decidere quando utilizzare il tuo tool.
  • Limita gli input numerici (clamp). I modelli di IA spesso inviano numeri inaspettati come 0 o 100.
  • Gestisci le eccezioni. Un crash nel tuo server può interrompere l'intera connessione.

Test e deployment Non aspettare di testare in Claude. Usa prima l'MCP Inspector. Esegui:

uv run mcp dev server.py

Questo apre un'interfaccia locale all'indirizzo http://localhost:5173. Puoi testare tool, resource e prompt in un unico posto.

Connessione a Claude Desktop: Aggiorna il tuo file di configurazione per includere il tuo server. Usa il percorso completo del file server.py. Usa sempre uv run invece del semplice comando python per evitare errori di ambiente.

Connessione a Claude Code: Usa il comando CLI:

claude mcp add github-tools -- uv run python /path/to/server.py

Costruire server MCP personalizzati ti permette di portare dati in tempo reale nei tuoi workflow di IA.

Fonte: https://dev.to/moksh/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide-397k

Comunità di apprendimento opzionale: https://t.me/GyaanSetuAi