italia-mcp

Servizi italiani essenziali per assistenti vocali, via MCP. Meteo, allerte della Protezione Civile, notizie ANSA, novità editoriali e promemoria — in italiano, con 9 strumenti in tutto.

Italian essentials (weather, Civil Protection alerts, ANSA news, reminders) as a Model Context Protocol server. Tool descriptions and responses are in Italian.

Nato per il chatbot vocale xiaozhi-esp32 (il "panda"), ma è un normale server MCP: funziona con Claude Desktop, Cursor, Cherry Studio e qualsiasi client compatibile.

⬇️ Scarica per Windows

PandaItalia.exe · 19 MB · nessuna installazione

Un file, doppio clic. Python non serve. Incolli l'indirizzo del tuo dispositivo una volta sola: viene salvato e dal secondo avvio il collegamento parte da solo.

1. Su xiaozhi.me → Configure → Extensions: togli la spunta a Weather e premi Save

2. Sempre lì → MCP Endpoint → icona copia

3. Avvia il programma → Incolla → Collega

Poi chiedi al tuo dispositivo: "Che tempo fa a Gallarate?"

L'eseguibile non è firmato: al primo avvio Windows mostra "Windows ha protetto il PC" → Ulteriori informazioni → Esegui comunque.

È pensato per la prova rapida. Windows va in sospensione e i riavvii di Windows Update interrompono il collegamento circa una volta al mese: per l'uso continuativo vedi la guida Raspberry.

Su macOS e Linux, e per chi preferisce Python: guida PC · tutte le versioni

Related MCP server: Weather MCP Server

Perché esiste

I server MCP meteo che si trovano in giro sono pensati per assistenti da scrivania, dove il contesto è enorme e nessuno conta i byte. Su un dispositivo vocale basato su ESP32 i vincoli sono un altro mondo:

L'elenco degli strumenti viaggia in ogni richiesta al modello: è lì che si vince o si perde. Tutto il resto del progetto discende da questo.

Strumenti

Installazione

pip install italia-mcp

Oppure, dalla sorgente:

git clone https://github.com/BorisLandoni/italia-mcp.git
cd italia-mcp
python3 -m venv .venv
./.venv/bin/python -m pip install -e .

Provalo subito, senza collegare niente

python prova.py

Chiama tutti gli strumenti uno per uno e misura quanto pesa ogni risposta:

[            ok]  148 byte    448 ms  meteo_adesso
[            ok]  228 byte   1010 ms  allerte_protezione_civile
[            ok]  371 byte    685 ms  novita_futura [rivista]
...
Risposta piu' pesante: 409 byte su un limite di 1024.
Tutti gli strumenti rispondono correttamente.

Per avviare il server vero:

italia-mcp

Il cursore resta fermo e non compare nulla: è corretto. Il server parla MCP su stdin/stdout e aspetta un client. Se stampasse qualcosa, romperebbe il protocollo.

Guide dettagliate

• Installare e provare su PC — Windows, macOS, Linux, passo passo

• Raspberry Pi come gateway sempre acceso — servizio systemd, riavvio automatico, log, aggiornamenti

• Collegare il panda (xiaozhi) — endpoint MCP e ponte

• Elecrow AI Panda ChatBot — guida specifica per quel dispositivo, e stato della ricerca sui sorgenti del firmware

• Creare l'eseguibile Windows — per chi vuole compilarlo

Uso con Claude Desktop, Cursor e simili

{
  "mcpServers": {
    "italia": { "command": "italia-mcp" }
  }
}

Uso con il panda (xiaozhi)

Il panda non chiama un URL: è il tuo server che deve collegarsi all'endpoint MCP del dispositivo e tenere aperta la connessione. Serve il ponte ufficiale mcp_pipe.py.

1. Nella console di xiaozhi.me apri Configure → Extensions → MCP Endpoint e copia l'indirizzo wss://api.xiaozhi.me/mcp/?token=... (è un segreto, trattalo come una password).

2. Togli la spunta all'estensione ufficiale Weather, altrimenti il modello ha due strumenti meteo e sceglie a caso.

3. Avvia il ponte:

pip install italia-mcp websockets python-dotenv
export MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=..."
python mcp_pipe.py xiaozhi/italia_server.py

Vedi xiaozhi/ per gli script pronti e la guida passo passo.

Vincoli della piattaforma da rispettare

Dalla documentazione ufficiale:

• la risposta di uno strumento è limitata a circa 1.024 byte;

• l'elenco degli strumenti ha un tetto misurato in token;

• ogni endpoint ha un limite di connessioni: usa un solo server MCP, non uno per servizio;

• mai print() nel codice di uno strumento: stdin/stdout sono il canale di trasporto.

Fonti dei dati

Nessuna chiave API richiesta.

Nota importante sulle allerte

Il bollettino della Protezione Civile esce entro le 16:00 e il mirror può avere qualche ora di ritardo. Il codice non si fida del nome del file: legge la finestra di validità dichiarata dentro il bollettino e usa solo quello valido in questo momento. Se nessuno è valido, lo dice invece di rispondere con dati vecchi. Ogni risposta include valido_fino.

Questo software non è un servizio di allerta ufficiale e non sostituisce i canali della Protezione Civile. Per le emergenze fai sempre riferimento alle fonti ufficiali.

Limiti noti

• Non può svegliare il dispositivo. I promemoria si consultano a voce, non suonano da soli: nel protocollo xiaozhi il server non può iniziare una conversazione.

• Non riproduce musica. Il canale audio è Opus binario, gli strumenti MCP scambiano solo testo.

• I promemoria sono salvati in un file locale, senza account: chi ha accesso al server li vede tutti.

Personalizzare le fonti

Le fonti di novita_futura sono ridefinibili con la variabile d'ambiente ITALIA_MCP_FONTI, nel formato chiave=URL|Etichetta;chiave2=URL2|Etichetta2: chi usa il pacchetto può puntarlo ai propri feed.

Licenza

Codice: MIT. I dati restano dei rispettivi titolari, alle licenze indicate sopra.

Crediti

Sviluppato da Boris Landoni con l'assistenza di Claude (Anthropic), per Futura Group Srl — editore di Elettronica In e Elettronica In PRO.