pyviaggiatreno

pyviaggiatreno is a monorepo that ships two complementary packages for working with the ViaggiaTreno APIs — the real-time information service of the Italian Railways (Trenitalia / RFI):

• viaggiatreno — a pure Python client library, with no MCP dependencies
• viaggiatreno-mcp — a Model Context Protocol server that exposes those APIs as tools for AI agents

The two live in separate subfolders under packages/, so you can install only the library if you are building an app, or the MCP server if you want an AI agent to query train information in natural language.

The core library: viaggiatreno

A pure Python client for the ViaggiaTreno APIs. Install it with:

pip install viaggiatreno

Features:

• 🚄 Async/await HTTP client built on httpx
• 📊 Strongly-typed Pydantic models
• 🔄 Intelligent parsing (JSON, plain text, HTML fragments)
• ⚡ Handles ViaggiaTreno quirks (204 No Content, JavaScript date formats, etc.)
• 🇮🇹 Full coverage of the Italian railways endpoints (20+)

A quick example — the departures board from Milano Centrale (station code S01700):

from viaggiatreno import ViaggiaTrenoClient
from datetime import datetime
import asyncio

async def main():
    client = ViaggiaTrenoClient()

    # Station autocomplete
    stations = await client.autocompleta_stazione("milano")
    print(stations)

    # Departures board
    departures = await client.partenze("S01700", datetime.now())
    for train in departures:
        print(f"{train.numeroTreno} → {train.destinazione} ({train.ritardo} min delay)")

asyncio.run(main())

The MCP server: viaggiatreno-mcp

An MCP server that makes those same APIs available to Claude, Kiro and any other MCP-compatible agent.

pip install viaggiatreno-mcp
viaggiatreno-mcp

The tools it exposes:

Beyond simply wrapping the endpoints, the server adds some AI-friendly conveniences:

• 🤖 AI-ready tool registration
• 🔗 Automatic parameter resolution (e.g. derive trip details from just a train number)
• 🧵 Async, concurrent tool execution

Registering the MCP server

The recommended way is uvx (which requires uv): it runs the server in an isolated environment with no manual install.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "viaggiatreno": {
      "command": "uvx",
      "args": ["viaggiatreno-mcp"]
    }
  }
}

Kiro (~/.kiro/settings/mcp.json) and other clients that share the same format (Cursor, Windsurf, VS Code MCP):

{
  "mcpServers": {
    "viaggiatreno": {
      "command": "uvx",
      "args": ["viaggiatreno-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

If you already ran pip install viaggiatreno-mcp, you can use "command": "viaggiatreno-mcp" instead. Remember to restart the client after saving the configuration.

Development

git clone https://github.com/matteoredaelli/pyviaggiatreno.git
cd pyviaggiatreno

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run the MCP server
python -m viaggiatreno_mcp.server

Both packages are published to PyPI from the same monorepo via GitHub Actions, using Trusted Publishing (OIDC) triggered on a version tag.

Why it is useful

With viaggiatreno-mcp connected, you can ask an AI agent things like “when is the next train from Milano Centrale to Roma Termini and is it on time?” or “what’s the status of train 9611?” and get an answer pulled live from ViaggiaTreno. And if you want to build your own app or script, the viaggiatreno library gives you the same data with clean, typed Pydantic models.

The project is MIT licensed and available on GitHub.