italian-bus-search
An unofficial, read-only MCP server for live Italian bus and train searches, exposing normalized locations, one-way journeys, prices, availability, and links for booking on provider sites.
List bus providers (Itabus, Salemi, Federico, MarinoBus, FlixBus) and train operators (Trenitalia, Italo) with status and enabled capabilities.
Search bus stops/cities by partial name across one provider or all at once.
Search one-way bus journeys with departure/arrival, duration, fares, availability, and official booking links; partial results survive a failing provider.
Search train stations per operator (station IDs are operator-specific).
Search train journeys with legs, changes, total passenger price, live status, warnings (e.g. urban transfers excluded from fare, Cosenza-via-Paola connections), and timetable provenance.
Get live train status for a train number, service date, and origin — delay, cancellation, freshness.
Get live station arrival/departure boards.
Paginate with offset/limit, or use snapshot:true + searchId for stable, immutable paging (5-minute expiry).
Read-only by design: no accounts, bookings, payments, or CAPTCHA handling.
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., "@italian-bus-search Find one-way buses from Rome to Milan on 15 June"
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.
Italian Travel Search
An unofficial, read-only TypeScript service for live Italian coach and train searches through HTTP and Model Context Protocol interfaces.
The project hides provider-specific station catalogs, request formats, fare structures, and multi-leg responses behind one shared application core. Italo pricing initializes an anonymous technical session and temporary planning resource; customer login, fare selection, seat reservation, and payment are excluded.
This project is not affiliated with or endorsed by Itabus, Autoservizi Salemi, Autolinee Federico, MarinoBus, or FlixBus. Provider names and trademarks belong to their owners. Before enabling a live adapter, confirm that your use complies with the provider's terms, applicable law, and any required authorization. This repository does not grant data-extraction or redistribution rights.
Features
One response model for locations and journeys across different booking platforms.
Live adapters for five bus operators and two train operators.
Partial results when one provider fails and another succeeds.
MCP over local stdio or stateless Streamable HTTP at
/mcp, with backward-compatible bus tools and separate rail tools.Trenitalia and Italo station and journey searches directly from their live booking APIs.
Official links for continuing a search manually on provider sites.
Searches respect the requested departure day; city searches preserve all Itabus stops, with physical-stop names/addresses where available.
Rail warnings identify urban transfers excluded from the quoted fare.
Structured, provider-scoped errors instead of leaked upstream responses.
Finite upstream request timeouts and bounded asynchronous quote polling.
One-hour location caches and 60-second journey caches.
Opt-in immutable journey pagination with five-minute in-memory snapshots, shared by HTTP and MCP.
Per-client in-memory rate limiting at 60 requests per minute.
Offline tests with synthetic fixtures; the test suite never contacts provider sites.
A small runtime dependency surface: the official MCP SDK and Zod.
Related MCP server: soloway-mcp
Supported providers
Provider ID | Operator | Integration | Locations | Journeys |
| Itabus | Demandware endpoints | Live | Live |
| Autoservizi Salemi | Albatross tenant | Live | Live |
| Autolinee Federico | Albatross tenant | Live | Live |
| MarinoBus | Albatross tenant | Live | Live |
| FlixBus | Global FlixBus search API | Live | Live |
Public provider behavior and limitations are documented in the bus and train API guides below.
Train stations, journeys, prices and availability come directly from Trenitalia and Italo booking APIs. No timetable download, dataset, storage volume or initialization command is required. If one operator fails, its error is reported alongside the other operator's results. ViaggiaTreno and Italo live boards/standalone status remain independent; Italo quote sessions are cleaned up best-effort.
Requirements
Node.js 22.18 or newer
npm
Quick start
git clone https://github.com/Alexxanddr/italian-travel-search.git
cd italian-travel-search
npm install
cp .env.example .env
npm startThe server listens on http://127.0.0.1:3000 by default.
curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/providers
curl http://127.0.0.1:3000/train-providers
curl 'http://127.0.0.1:3000/locations?query=Roma&provider=marinobus'For journey searches, use today or a future date in Europe/Rome:
curl 'http://127.0.0.1:3000/journeys?origin=Roma&destination=Milano&date=YYYY-MM-DD&adults=1&children=0&provider=marinobus'YYYY-MM-DD is a placeholder and must be replaced before running the command.
Web frontend
The dark, Italian-language Binario interface lives in frontend/ in this repository. It searches bus and train journeys through the HTTP API, with a single origin/destination/date form, progressive results, stable snapshot pagination and official booking links. It has no account, payment, AI model or direct provider/MCPHub access in the browser.
From the repository root:
npm ci
npm ci --prefix frontend
npm start
# In another terminal, from the same repository root:
npm run web:dev
# Open http://127.0.0.1:5173The local frontend proxy defaults to the API at http://127.0.0.1:3000. Optional local configuration belongs in ignored frontend/.env.local; copy frontend/.env.example if needed. Never use browser-exposed VITE_* variables for credentials.
npm run build:all
# Install Chromium once before running browser tests:
cd frontend
npx playwright install chromium
cd ..
npm run check:allnpm run build and npm run check retain their existing backend behavior. The frontend shares domain types and keeps its own build lockfile. The existing root Dockerfile builds both parts into one image: Node serves the UI at /, the browser API at /api/*, the existing HTTP endpoints and MCP at /mcp, all on port 3000. No NGINX or second container is needed. The npm package remains API/MCP-focused and excludes frontend assets/tooling. See the frontend guide, single-image Docker packaging, and publication review. Publishing source code does not require hosting a live website.
The published image is multiarch: linux/amd64 and linux/arm64 share the same tag, and Docker selects the matching architecture automatically.
One image, one process
docker build -t italian-travel-search:local .
docker run --rm -p 127.0.0.1:3000:3000 italian-travel-search:local
# UI: http://127.0.0.1:3000/
# API: http://127.0.0.1:3000/api/providers (also /providers)
# MCP: http://127.0.0.1:3000/mcpWithout Docker, npm run build:all followed by node dist/index.js serves the same combined application. npm run web:dev remains the optional development server with live rebuilding.
HTTP interface
Method | Path | Purpose |
|
| Process liveness |
|
| Adapter status and operational reason |
|
| Train operators and configured schedule/price/live capabilities |
|
| Provider location search |
|
| Normalized one-way journey search |
|
| Trenitalia/Italo station search |
|
| Live rail journeys, availability and nullable prices |
|
| Standalone live status where enabled |
|
| Live arrivals/departures where enabled |
|
| Stateless MCP Streamable HTTP endpoint |
/locations and /journeys accept an optional provider parameter. Without it, all providers are queried independently and successful data is preserved alongside provider-scoped errors.
The complete contract is split into the Bus API and Train API, with shared behavior indexed in HTTP API.
MCP server
The simplest MCP configuration runs the published package directly with npx:
{
"mcpServers": {
"italian-travel-search": {
"command": "npx",
"args": ["-y", "italian-travel-search@latest"]
}
}
}Alternatively, build and start the local stdio server:
npm run build
npm run mcp:builtThe existing list_providers, search_locations, and search_journeys bus tools remain compatible. Location and journey searches accept optional offset/limit; increment offset by limit until truncated is false to retrieve every page. Rail adds list_train_providers, search_train_locations, search_train_journeys, get_train_status, and get_station_board. Trenitalia and Italo price and live adapters are enabled; Italo live tools retain date-unverified semantics.
For exhaustive journey searches, start with snapshot: true and continue
with only the returned searchId, offset and limit. This keeps
prices, errors, order and totals identical across pages. Expired IDs require
a new search. The same opt-in flow exists over HTTP; see
stable pagination.
{
"mcpServers": {
"italian-travel-search": {
"command": "node",
"args": ["/absolute/path/to/italian-travel-search/dist/mcp/stdio.js"]
}
}
}For a container or remote MCPHub deployment, start the HTTP process and point the client to http://italian-travel-search:3000/mcp. The container image is ghcr.io/alexxanddr/italian-travel-search:latest. No dataset initialization or persistent volume is needed.
See MCP interface for the authoritative tool contract, limits, errors, and development command.
Architecture
The application has four layers:
HTTP and MCP adapters validate their transport-specific requests;
shared validation and
SearchServiceorchestrate searches and partial results;each provider adapter translates a remote protocol into domain types;
the domain module owns normalized data and error contracts.
Provider adapters implement one shared interface, so callers do not know whether a result came from Itabus Demandware or an Albatross tenant. See Architecture for modules, seams, data flow, caches, and test strategy.
Development
npm run dev
npm run mcp
npm run checknpm run check runs the complete offline test suite, TypeScript type checking, and the configured lint check. To add an operator, follow Adding a provider; do not infer a new integration from HTML alone or copy credentials into fixtures.
Deployment
The default server deliberately binds to loopback and keeps rate-limit and cache state in process memory. Read Operations before placing it behind a reverse proxy or running multiple replicas.
Project documentation
HTTP API — shared behavior and error contract.
Bus API — bus providers, locations, journeys, and examples.
Train API — rail schedules, live prices/status, provenance, and examples.
MCP interface — authoritative tools, results, limits, and transport contract.
Architecture — modules, seams, flows, and design decisions.
Adding a provider — research, implementation, and verification checklist.
Operations — configuration, deployment constraints, and failure handling.
Glossary — stable project terminology.
Contributing — local workflow and pull-request expectations.
Security policy — private vulnerability reporting and supported versions.
Agent instructions — compact routing instructions for coding agents.
Scope and limitations
Searches are one-way only.
Availability is a provider-reported signal, not a seat or price guarantee.
Prices and schedules can change between search and purchase; rail results expose live observation and source metadata. The legacy field name
timetableSourceis retained for compatibility.Caches and rate limits reset when the process restarts and are not shared across replicas.
Upstream interfaces are unofficial and can change without notice.
Both interfaces intentionally exclude accounts, bookings, payments, and CAPTCHA handling.
Always complete and confirm a purchase on the official provider site linked by bookingUrl.
Contributing and security
Contributions are welcome; start with CONTRIBUTING.md. Report vulnerabilities privately according to SECURITY.md, not through a public issue.
License
Source code is available under the MIT License. The license covers this repository's code, not third-party data, provider trademarks, or access rights to upstream systems.
Train connections to Cosenza
Search Cosenza directly: the backend preserves native connections via Paola, including Italo services followed by a Trenitalia regional train when offered by the booking API. Results include both legs, their operators, the interchange and the combined passenger fare when fully available. The destination is never silently replaced with Paola. See Train API.
Available Tools
8 toolsget_station_boardGet train station boardBRead-onlyIdempotent
Get an operator station board with its observation timestamp. Live boards may be unavailable independently of schedules.
Inputs: provider (required), direction (required), stationId (required), stationName (required). Returns: source, station, provider, services, +2 more
get_train_statusGet train statusBRead-onlyIdempotent
Get live status using operator, train number, service date, and origin identity. Live status may be unavailable independently of schedules.
Inputs: origin (required), provider (required), serviceDate (required), trainNumber (required). Returns: source, cancelled, freshness, observedAt, +1 more
list_providersList Italian bus providersARead-onlyIdempotent
BUS ONLY. List configured bus/coach providers and their status. Never use this tool for trains or rail; use list_train_providers instead.
Inputs: no named parameters. Returns: providers
list_train_providersList Italian train providersARead-onlyIdempotent
TRAINS ONLY. Use for requests involving trains or rail. Lists train operators and whether schedule, price, live-status, and station-board capabilities are enabled.
Inputs: no named parameters. Returns: providers
search_journeysSearch Italian bus journeysARead-onlyIdempotent
BUS ONLY. Search one-way bus/coach journeys. Never use for trains or rail; use search_train_journeys instead. Results include official links for continuing manually on provider sites. For stable pagination start with snapshot:true; continue using only searchId, offset and limit.
Inputs: date, limit, adults, offset, +6 more. Returns: total, errors, journeys, searchId, +3 more
search_locationsSearch Italian bus locationsARead-onlyIdempotent
BUS ONLY. Find bus/coach location IDs and exact names. Never use for train stations; use search_train_locations instead. For an aggregate bus search, reuse exact names shared across providers.
Inputs: query (required), limit, offset, provider. Returns: total, errors, locations, truncated
search_train_journeysSearch Italian train journeysARead-onlyIdempotent
TRAINS ONLY. Requires origin, destination, and date. When the user states passenger counts, always pass adults and children explicitly. Each price is the total for those passengers; never infer discounts or convert it to a per-person price. For stable pagination start with snapshot:true; continue using only searchId, offset and limit.
Inputs: date, limit, adults, offset, +6 more. Returns: total, errors, journeys, searchId, +3 more
search_train_locationsSearch Italian train stationsARead-onlyIdempotent
TRAINS ONLY. Use for every request involving trains or rail to find operator-aware stations. Prefer names across operators; station IDs are operator-specific.
Inputs: query (required), limit, offset, provider. Returns: total, errors, locations, truncated
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a stated, distinct purpose, and descriptions strongly steer agents between bus and train variants. However, the generic-looking names `list_providers`, `search_journeys`, and `search_locations` are actually bus-only, while train equivalents are explicitly prefixed, creating a real risk of misselection before reading descriptions.
Verb usage is consistent (`list_`, `search_`, `get_`), but the subject naming is asymmetric: bus tools use unprefixed generic names while train tools use `train` prefixes. `get_station_board` lacks a train prefix despite being rail-oriented, adding to the mixed convention.
Eight tools is well-scoped for a bus-and-train journey search server. Each tool covers a distinct capability: providers, journey search, location lookup, live status, and station boards for the relevant modes.
The surface covers provider discovery, location resolution, journey search, live train status, and station boards, which is strong lifecycle coverage for a search-oriented server. Minor gaps include no explicit round-trip search and no bus live-status/station-board equivalents, though these may reflect upstream limitations.
Maintenance
Related MCP Connectors
AI marketplace — flights, tours, activities, transport & more via MCP. No auth required.
Omio MCP server for ChatGPT, Claude and any AI agent: search trips, find the cheapest day and start booking in your own Omio account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Omio yourself; Cotlet does not store your password and you need no Omio API key. About the official Omio API: Omio has no public API for your own account (checked 24 Oct 2026). Its affiliate programme lists a Search API for partners, and its app in ChatGPT searches trips; Your Bookings, saved travelers and checkout work only on omio.com and in the Omio app. Setup and FAQ: https://cotlet.dev/integrations/omio-api-mcp-server
The Ferryhopper MCP server is a connector for LLMs and AI Agents in maritime travel that exposes ferry routes, schedules, and booking options. It enables AI assistants to search ports and connections across 33 countries and 190+ ferry operators, provide real-time ferry itineraries with indicative prices, and assist users with planning island-hopping or multi-leg journeys by processing natural language queries about ferry times, passenger counts, and travel durations.
Search MCP servers, agent skills and AI tools by task. Read-only, no API key.
Related MCP Servers
- AlicenseAqualityDmaintenanceReal-time train, bus, ferry and private transfer prices between 40+ Italian cities4MIT
- AlicenseNot gradedqualityCmaintenanceLive intercity bus-trip search across Ukraine and Europe — real-time prices, seats, carriers, cheapest-day-of-month calendar, and trip details with passenger discounts. Read-only, no API key; also available as a hosted remote endpoint at https://mcp.soloway.com.ua/mcp.MIT

virail-mcpofficial
AlicenseAqualityCmaintenanceEnables MCP-compatible AI agents to search live Virail transport connections across trains, buses, flights, ferries, and carpooling, returning real prices, schedules, and booking links.41MIT- AlicenseAqualityBmaintenanceEnables Claude, ChatGPT, Gemini, and other MCP clients to find, rank, and vet intercity bus options in India, generate official booking links, interpret seat maps, and guide users through safe booking and pre-payment checks.12MIT