Skip to main content
Glama

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

viaggiatreno

Libreria client HTTP async (core, nessuna dipendenza MCP)

viaggiatreno

viaggiatreno-mcp

Server MCP per agenti AI (Claude, Kiro, Cursor, …)

viaggiatreno-mcp

viaggiatreno-crawler

Poller che interroga le API nel tempo e salva in SQLite

viaggiatreno-crawler

Non esiste un pacchetto CLI generico separato: gli unici comandi da riga di comando sono gli entry point viaggiatreno-mcp (server MCP) e viaggiatreno-crawler (crawler).

viaggiatreno - Core Library ⭐

Pure Python client library for ViaggiaTreno APIs. No MCP dependencies.

pip install viaggiatreno

Usage:

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-mcp

Start server:

viaggiatreno-mcp

Configure in Claude, pi, or other AI tools to use these tools:

  • autocompleta_stazione - Station autocomplete

  • cerca_stazione - Search stations

  • dettaglio_stazione - Station details

  • partenze - Departures board

  • arrivi - Arrivals board

  • stato_treno - Train status & full route

  • E 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-crawler

Avvio:

viaggiatreno-crawler eventi --regione 1 --db-path data/eventi.db

Flusso: 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:


🚀 Quick Start

Installation

# Core library only
pip install viaggiatreno

# With MCP server
pip install viaggiatreno-mcp

# With crawler (SQLite poller)
pip install viaggiatreno-crawler

Using 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:

  1. Fork the repo

  2. Create a feature branch

  3. Submit a PR


📞 Support


🔄 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/dev e 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:

  1. PyPI account (https://pypi.org)

  2. Per ciascun pacchetto (viaggiatreno, viaggiatreno-mcp), aggiungi un Trusted Publisher: owner matteoredaelli, repo pyviaggiatreno, workflow publish-pypi.yml, environment pypi

  3. Crea l'environment pypi in 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 packages

Both viaggiatreno and viaggiatreno-mcp (e viaggiatreno-crawler) will be published to PyPI with the same version.


Available Tools

23 tools
autocompleta_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

    B3.4/5.0

    Scored across 23 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables real-time Indian Railways information retrieval, including live train running status, station schedules, and upcoming arrivals/departures.
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides real-time Belgian rail (SNCB/NMBS) data via the iRail API, enabling AI agents to query train schedules and live information.
      78 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -