
italy-trains-viaggiatreno-mcp
io.github.matteoredaelli/italy-trains-viaggiatreno-mcp
Italian railways (Trenitalia, ViaggiaTreno): live departures, delays, train status, routes.
Documentation
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) eviaggiatreno-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 autocompletecerca_stazione- Search stationsdettaglio_stazione- Station detailspartenze- Departures boardarrivi- Arrivals boardstato_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.
โจ 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-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:
- Fork the repo
- Create a feature branch
- Submit a PR
๐ Support
- ๐ Bug reports
- ๐ฌ Discussions
- ๐ง 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, environmentpypi - Crea 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 packages
Both viaggiatreno and viaggiatreno-mcp (e viaggiatreno-crawler) will be published to PyPI with the same version.
viaggiatreno-mcppip install viaggiatreno-mcpRelated Servers
io.github.matteoredaelli/active-directory-ldap-mcp
Active Directory / LDAP MCP server: find users, groups, memberships; read-only security audits.
io.github.matteoredaelli/atm-milano-mcp
Milan public transport (ATM): trip planning, lines, stops, live waits and metro stations.
io.github.matteoredaelli/mcpad
Read-only Active Directory / LDAP: users, groups, memberships and security audits.