ViaggiaTreno MCP Server
This MCP server exposes real-time Italian railway data from the unofficial ViaggiaTreno APIs, letting an AI agent look up stations, live train boards, train status, network segments, disruptions, weather and more.
Station lookup: autocomplete stations by name prefix, search structured station records, get full station details (coordinates, city, region, type), list all stations in a region, and resolve a station's region code.
Technical nodes: autocomplete NTS railway nodes (bivi, deviatoi, PC) with RICS codes.
Live boards: real-time departures and arrivals for any station, with delays, platforms, circulation status and origin/destination codes.
Journey planning: find direct (no-change) trains between two stations for the current day.
Train tracking: search active runs by train number, get full real-time status with all commercial stops (scheduled/actual times, platforms, delays, suppressions), and get the visual tree itinerary (tratteCanvas).
Delay prediction: estimate a train's likely predecessor on shuttle/suburban lines to anticipate knock-on delays.
Network monitoring: list railway segments with occupancy and coordinates, and get trains currently running on a specific segment (region-scoped IDs).
Network stats: total scheduled and currently circulating trains nationwide.
Infomobility: full disruption/work notices, compact titles, and the scrolling ticker.
Extras: weather forecasts per region, and the UI translation dictionary for 9 languages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ViaggiaTreno MCP Server mostrami le partenze in tempo reale da Milano Centrale"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pyviaggiatreno
Monorepo Python (workspace uv) basato sulle API non ufficiali di
ViaggiaTreno (treni in Italia): libreria client,
server MCP e crawler che salva dati storici in SQLite.
📦 Packages
Package | Ruolo | PyPI |
Libreria client HTTP async (core, nessuna dipendenza MCP) |
| |
Server MCP per agenti AI (Claude, Kiro, Cursor, …) |
| |
Poller che interroga le API nel tempo e salva in SQLite |
|
Non esiste un pacchetto CLI generico separato: gli unici comandi da riga di comando sono gli entry point
viaggiatreno-mcp(server MCP) eviaggiatreno-crawler(crawler).
viaggiatreno - Core Library ⭐
Pure Python client library for ViaggiaTreno APIs. No MCP dependencies.
pip install viaggiatrenoUsage:
from viaggiatreno import ViaggiaTrenoClient
import asyncio
async def main():
client = ViaggiaTrenoClient()
# Get station suggestions
stations = await client.autocompleta_stazione("milano")
print(stations)
# Get departures
departures = await client.partenze("S01700", datetime.now())
for train in departures:
print(f"{train.compNumeroTreno} → {train.destinazione} ({train.ritardo} min delay)")
asyncio.run(main())viaggiatreno-mcp - MCP Server
Model Context Protocol server for Claude, pi, and other AI agents.
pip install viaggiatreno-mcpStart server:
viaggiatreno-mcpConfigure in Claude, pi, or other AI tools to use these tools:
autocompleta_stazione- Station autocompletecerca_stazione- Search stationsdettaglio_stazione- Station detailspartenze- Departures boardarrivi- Arrivals boardstato_treno- Train status & full routeE altri...
viaggiatreno-crawler - Crawler → SQLite
Poller che usa la libreria core per raccogliere nel tempo dati storici sui treni (numeri, ritardi, binari, fermate) in un database SQLite locale — utile per KPI che le API ViaggiaTreno non espongono (sono solo "stato attuale", non storiche).
pip install viaggiatreno-crawlerAvvio:
viaggiatreno-crawler eventi --regione 1 --db-path data/eventi.dbFlusso: stazioni (elencoStazioni e quelle scoperte da tabelloni e itinerari) →
tabelloni di partenze/arrivi dei capolinea → andamento_treno una volta alla partenza e
una dopo l'arrivo previsto → upsert in SQLite, con una coda di lavori a scadenza.
Dettagli in
packages/viaggiatreno_crawler/README.md;
tabelle, schema ed esempi di dati in README-DB.md.
Related MCP server: MCP Trenitalia
✨ Features
Core Library
🚄 Async/await HTTP client with
httpx📊 Strongly-typed Pydantic models
🔄 Intelligent parsing (JSON, plain text, HTML fragments)
⚡ Handles ViaggiaTreno quirks (204 No Content, JS date formats, etc.)
🇮🇹 Full coverage of Italian railways
MCP Server
🤖 AI-ready tool registration
🔗 Automatic parameter resolution (derive trip details from train number)
📱 Works with Claude, pi, and other MCP clients
🧵 Async concurrent tool execution
📚 Documentation
See main documentation files:
VIAGGIATRENO.md - API reference (20+ endpoints)
TRENORD.md - GTFS Trenord structure
ENTITA.md - Data model & schema
GLOSSARIO.md - Railway terminology
COPERTURA_GEOGRAFICA.md - Geographic coverage
🚀 Quick Start
Installation
# Core library only
pip install viaggiatreno
# With MCP server
pip install viaggiatreno-mcp
# With crawler (SQLite poller)
pip install viaggiatreno-crawlerUsing the Library
from viaggiatreno import ViaggiaTrenoClient
from datetime import datetime
client = ViaggiaTrenoClient()
# Get train departures from Milano Centrale
trains = await client.partenze("S01700", datetime.now())
for train in trains:
print(
f"{train.numeroTreno}: {train.destinazione} at {train.compOrarioPartenza} (delay: {train.ritardo}m)"
)Using MCP Server
Il modo consigliato è uvx (richiede uv), che
esegue il server in un ambiente isolato senza installarlo a mano.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json
su macOS, %APPDATA%\Claude\claude_desktop_config.json su Windows):
{
"mcpServers": {
"viaggiatreno": {
"command": "uvx",
"args": ["viaggiatreno-mcp"]
}
}
}Kiro (~/.kiro/settings/mcp.json) e altri client con lo stesso formato
(Cursor, Windsurf, VS Code MCP):
{
"mcpServers": {
"viaggiatreno": {
"command": "uvx",
"args": ["viaggiatreno-mcp"],
"disabled": false,
"autoApprove": []
}
}
}In alternativa, se hai già fatto pip install viaggiatreno-mcp, usa
"command": "viaggiatreno-mcp" (o "command": "python", "args": ["-m", "viaggiatreno_mcp"]).
Riavvia il client dopo aver salvato la configurazione.
Dettagli completi in packages/viaggiatreno_mcp/README.md.
🛠️ Development
Il repo è un workspace uv con 3 pacchetti sotto packages/.
# Clone repo
git clone https://github.com/matteoredaelli/pyviaggiatreno.git
cd pyviaggiatreno
# Install workspace + dev deps (editable)
uv sync
# Lint + type check + format check
make lint # ruff format --check + ruff check + pyright
# Run tests
make pytest # oppure: uv run pytest
# Run MCP server
make run # oppure: uv run viaggiatreno-mcp
# Run crawler
make crawler-eventi
# Build all packages
make build # oppure: uv build📄 License
GNU General Public License v3.0 o successiva (GPL-3.0-or-later).
Ogni file sorgente riporta l'intestazione SPDX-License-Identifier: GPL-3.0-or-later.
🤝 Contributing
Contributions welcome! Please:
Fork the repo
Create a feature branch
Submit a PR
📞 Support
📧 Email: matteo.redaelli@gmail.com
🔄 GitHub Actions Workflow
La repo ha 3 workflow automatici:
1. Tests & Linting (tests.yml)
✅ Ruff linting
✅ Pyright type checking
✅ Pytest unit tests
🔄 Trigger: Ogni commit su
main/deve PR🎯 Purpose: Verifica codice quality
2. Test Build (test-build.yml)
✅ Build entrambi i pacchetti
✅ Testa installazione wheel
🔄 Trigger: Commit su
packages/o workflow_dispatch🎯 Purpose: Verifica che la build funzioni (senza pubblicare)
3. Publish to PyPI (publish-pypi.yml)
✅ Build entrambi i pacchetti
✅ Pubblica su PyPI
✅ Crea GitHub Release con artifacts
🔄 Trigger: Tag push (e.g.
git push origin v0.1.0)🎯 Purpose: Pubblica su PyPI (una sola volta)
Vedi RELEASE.md per istruzioni dettagliate.
📦 Publishing to PyPI
Prerequisites
Il publish usa Trusted Publishing (OIDC) — nessun token da gestire. Configurazione una tantum:
PyPI account (https://pypi.org)
Per ciascun pacchetto (
viaggiatreno,viaggiatreno-mcp), aggiungi un Trusted Publisher: ownermatteoredaelli, repopyviaggiatreno, workflowpublish-pypi.yml, environmentpypiCrea l'environment
pypiin GitHub (Settings → Environments)
Release Process
# 1. Commit & push
git add .
git commit -m "feature: add X"
git push origin main
# 2. Create tag (triggers publish workflow)
git tag v0.2.0
git push origin v0.2.0
# 3. GitHub Actions automatically publishes both packagesBoth viaggiatreno and viaggiatreno-mcp (e viaggiatreno-crawler) will be published to PyPI with the same version.
Available Tools
23 toolsautocompleta_stazioneAutocompleta StazioneA
Suggerisce stazioni ferroviarie per prefisso del nome (es. 'firenze', 'milano'). Restituisce nome esteso e codice stazione (es. S01700 per Milano Centrale). È l'endpoint consigliato per ottenere i codici stazione da usare nei tabelloni e nei dettagli.
Inputs: prefisso (required). Returns: result
autocompleta_stazione_ntsAutocompleta Stazione NtsA
Autocompletamento di stazioni e nodi tecnici ferroviari (bivi BIVIO, deviazioni DEV., posti di comunicazione PC) con codici RICS a 9-11 cifre (iniziano con 83...). Nota: questi codici NTS non vanno usati con gli altri endpoint ordinari.
Inputs: prefisso (required). Returns: result
cerca_numero_trenoCerca Numero TrenoA
Cerca le corse attive associate a un numero di treno (es. 9611). Restituisce i dati identificativi essenziali: stazione di origine, data di partenza e millisecondi da passare a stato_treno o itinerario_treno_canvas.
Inputs: numero_treno (required). Returns: result
cerca_stazioneCerca StazioneA
Cerca stazioni il cui nome inizia con la stringa specificata. Restituisce informazioni anagrafiche strutturate (id stazione, nome lungo, nome breve, etichetta/città).
Inputs: prefisso (required). Returns: result
codice_regione_stazioneCodice Regione StazioneA
Restituisce il codice numerico di regione associato a una determinata stazione (es. 'S01700' -> 1 Lombardia).
Inputs: codice_stazione (required). Returns: result
dettaglio_stazioneDettaglio StazioneB
Restituisce i dettagli completi di una stazione ferroviaria: coordinate geografiche (latitudine/longitudine), città, regione e tipologia. Se codice_regione non viene fornito, viene recuperato automaticamente.
Inputs: codice_stazione (required), codice_regione. Returns: result
dizionario_linguaDizionario LinguaA
Restituisce il dizionario delle traduzioni delle stringhe dell'interfaccia ViaggiaTreno. Lingue supportate: 'it', 'en', 'de', 'fr', 'sp', 'ro', 'jp', 'zh', 'ru'.
Inputs: id_lingua. Returns: object
elenco_stazioni_regioneElenco Stazioni RegioneB
Restituisce l'elenco di tutte le stazioni ferroviarie appartenenti a una specifica regione (1=Lombardia, 2=Liguria, 3=Piemonte, 5=Lazio, 8=Emilia Romagna, 13=Toscana, 0=Stazioni principali italiane, ecc.) con le relative coordinate geografiche.
Inputs: codice_regione (required). Returns: result
elenco_tratte_ferroviarieElenco Tratte FerroviarieA
Restituisce i segmenti della rete ferroviaria (coppie di nodi ferroviari con coordinate geografiche) e l'indicazione se ciascun segmento è attualmente occupato da almeno un treno in viaggio. Le categorie filtrabili (separate da virgola) includono: 'ES*,IC,EXP,EC,EN,REG'. id_regione filtra i segmenti per area geografica (0=tutta Italia, 1-22=singola regione, stesso codice di elenco_stazioni/regione): attenzione, filtra i segmenti non i treni, quindi un segmento di confine regionale può comunque restituire treni di lunga percorrenza che solo transitano in quell'area. Gli ID tratta_ab/tratta_ba restituiti sono numerati per regione: vanno riusati con lo stesso id_regione in treni_su_tratta, altrimenti si ottengono i treni di un segmento fisicamente diverso.
Inputs: categorie, id_regione. Returns: result
itinerario_treno_canvasItinerario Treno CanvasB
Restituisce la rappresentazione visuale ad albero (tratteCanvas) dell'itinerario del treno, indicando fermata per fermata se la partenza o l'arrivo sono già avvenuti e se il treno è fermo in stazione.
Inputs: numero_treno (required), data_partenza (required), codice_stazione_origine (required). Returns: result
meteo_stazioniMeteo StazioniB
Restituisce le previsioni meteo per le stazioni di una specifica regione (es. 1=Lombardia, 13=Toscana). Nota: l'API ufficiale potrebbe restituire un insieme vuoto per alcune regioni se il dato non è disponibile.
Inputs: codice_regione (required). Returns: object
notizie_infomobilitaNotizie InfomobilitaA
Restituisce le notizie dettagliate di infomobilità in tempo reale: avvisi sulla circolazione, ritardi eccezionali, guasti, modifiche di percorso o scioperi. Impostare solo_lavori=True per ottenere l'elenco dei lavori programmati.
Inputs: solo_lavori. Returns: result
predecessore_trenoPredecessore TrenoA
Stima il treno 'predecessore' su una linea a spola/suburbana (stesso materiale rotabile che fa avanti e indietro, es. linee S): se il predecessore è in ritardo, è probabile che questo treno lo sarà anch'esso, prima ancora che il sito mandi un avviso. ATTENZIONE: è una stima per prossimità temporale (arrivo più recente alla stessa stazione, stesso operatore, stessa linea), non un dato certo dell'API. Funziona bene su linee a spola ad alta frequenza (verificato su S8 Lecco-Milano Porta Garibaldi e sulla Como/Chiasso-Milano Porta Garibaldi); NON è adatta a linee regionali a lunga percorrenza con poche corse al giorno (es. Milano Centrale-Tirano), dove restituirà null o un risultato poco significativo. Se codice_stazione_origine e data_partenza non vengono forniti, vengono determinati automaticamente tramite il numero di treno.
Inputs: numero_treno (required), data_partenza, finestra_minuti, codice_stazione_origine. Returns: result
profilo_stazioneProfilo StazioneA
Analisi di una stazione dai tabelloni di partenze e arrivi di adesso (o di data_ora, formato ISO): anagrafica (nome, citta', regione, coordinate), ruolo (capolinea, transito, mista), numero di treni e cancellati, frequenza (treni all'ora, intervalli, regolarita'), binari programmati ed effettivi con i collegamenti che vi passano, e i collegamenti origine -> destinazione con la loro frequenza. E' una fotografia della finestra dei tabelloni (poche ore), non uno storico. Fa 4 richieste (partenze, arrivi, regione, dettaglio); con con_dettaglio=false 2.
Inputs: codice_stazione (required), data_ora, con_dettaglio. Returns: Fotografia di una stazione ricavata da un insieme di corse dei suoi tabelloni.
profilo_trenoProfilo TrenoA
Analisi di un treno da andamentoTreno: stato (regolare, soppresso, parziale), avanzamento, itinerario programmato, fermate nell'ordine di marcia con orari e binari programmati/effettivi, archi tra fermate consecutive (tempi di percorrenza, ritardo accumulato, soste), collegamento programmato ed effettivo e anomalie. Se codice_stazione_origine e data_partenza mancano si ricavano dal numero di treno. Restituisce null se l'API non ha il treno (prima della partenza o dopo il reset notturno).
Inputs: numero_treno (required), data_partenza, codice_stazione_origine. Returns: result
statistiche_servizioStatistiche ServizioA
Restituisce le statistiche della rete ferroviaria nazionale in tempo reale: numero complessivo di treni programmati per la data odierna e numero di treni attualmente in circolazione.
Inputs: no named parameters. Returns: result
stato_trenoStato TrenoA
Restituisce lo andamento e lo stato in tempo reale di un treno: ritardo attuale, ultimo rilevamento con stazione e orario, stato di marcia (regolare, soppresso, parzialmente soppresso), e l'elenco completo di tutte le fermate commerciali con orario programmato, orario effettivo e binari. Se codice_stazione_origine e data_partenza non vengono forniti, vengono determinati automaticamente tramite il numero di treno.
Inputs: numero_treno (required), data_partenza, codice_stazione_origine. Returns: result
tabellone_arriviTabellone ArriviA
Restituisce il tabellone degli arrivi in tempo reale per una stazione ferroviaria (es. 'S01700' per Milano Centrale). Fornisce: treni in arrivo, stazione di provenienza, orario programmato, ritardo in minuti, binario programmato ed effettivo, e se il treno è già giunto in stazione.
Inputs: codice_stazione (required), data_ora. Returns: result
tabellone_partenzeTabellone PartenzeB
Restituisce il tabellone delle partenze in tempo reale per una stazione ferroviaria (es. 'S01700' per Milano Centrale, 'S08409' per Roma Termini). Fornisce: treni in partenza, destinazione, orario programmato, ritardo in minuti, binario programmato ed effettivo, stato di circolazione e codice origine/data per ulteriori approfondimenti.
Inputs: codice_stazione (required), data_ora. Returns: result
ticker_infomobilitaTicker InfomobilitaB
Restituisce gli avvisi brevi scorrevoli della striscia informativa del portale ViaggiaTreno.
Inputs: no named parameters. Returns: result
titoli_infomobilitaTitoli InfomobilitaB
Restituisce i soli titoli sintetici degli avvisi di infomobilità o dei lavori programmati (versione compatta per panoramica rapida).
Inputs: solo_lavori. Returns: result
treni_diretti_tra_stazioniTreni Diretti Tra StazioniA
Restituisce i treni DIRETTI (senza cambi) tra due stazioni nella giornata corrente (es. da 'S01700' Milano Centrale a 'S06421' Firenze Santa Maria Novella). Non gestisce percorsi che richiedono un interscambio: in tal caso la lista può risultare vuota anche se un collegamento con cambio esiste. Endpoint non documentato nelle fonti note, trovato nello script ufficiale del sito ViaggiaTreno e verificato dal vivo.
Inputs: id_stazione_a (required), id_stazione_da (required). Returns: result
treni_su_trattaTreni Su TrattaA
Restituisce i treni attualmente in circolazione su uno specifico segmento di tratta ferroviaria. Richiede gli identificativi numerici nei due sensi (tratta_ab e tratta_ba) e lo stesso id_regione usati nella chiamata a elenco_tratte_ferroviarie che li ha prodotti: gli ID sono numerati per regione, non sono identificativi globali della rete.
Inputs: tratta_ab (required), tratta_ba (required), categorie, id_regione. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools target distinct concerns (boards, status, routes, info-mobility), but a few pairs genuinely blur: cerca_stazione and autocompleta_stazione both do prefix matching on station names, and stato_treno vs profilo_treno vs itinerario_treno_canvas all return train progress with overlapping data. Descriptions are detailed and frequently disambiguate (note on NTS codes, note on direct-only routes), which pulls this up to a middling score.
All names are consistently snake_case Italian, mostly noun-first with a qualifier (profilo_stazione, tabellone_partenze, treni_su_tratta), which is easy to read and predict. Minor deviations exist where verb-first forms appear (cerca_*, autocompleta_*) for tasks that are otherwise noun-named, but overall the set feels coherent.
23 tools is in the heavy 16-25 band. For a rich real-time rail API this is defensible, but several slots are low-value or redundant (titoli_infomobilita overlaps notizie/ticker, cerca_stazione vs autocompleta_stazione, autocompleta_stazione_nts serves an edge case). Some consolidation would tighten the surface.
The read-only ViaggiaTreno domain is well covered: station lookup/details/region, live departures/arrivals, train status/route/canvas, network segments and trains-on-segment, info-mobility, weather, and stats. The main gap is journey planning beyond direct trains (no multi-leg/change routing), plus no historical data, but agents can work around these.
Maintenance
Related MCP Connectors
Belgian trains for AI agents: live journeys, departures, delays, disruptions. Free, no key.
Read-only airport delay, weather, and 24h forecast tools for AI assistants. Airport-level only.
Live Polish rail data: boards for every station, delays, PLK disruptions, train punctuality.
Live UK rail boards, journey planning, train history, units, lifts, disruptions, punctuality.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables real-time Indian Railways information retrieval, including live train running status, station schedules, and upcoming arrivals/departures.ISC
- AlicenseNot gradedqualityBmaintenanceAn MCP server for real-time Italian railway data, enabling natural language queries about train schedules, delays, departures, arrivals, and live tracking via the Viaggiatreno API.7MIT
- AlicenseNot gradedqualityCmaintenanceProvides real-time Belgian rail (SNCB/NMBS) data via the iRail API, enabling AI agents to query train schedules and live information.78 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to query real-time Indian Railways data including train schedules, live status, PNR status, seat availability, fares, and coach positions via the Model Context Protocol.-