Auckland Transport MCP Server
A Model Context Protocol (MCP) server for connecting to the Auckland Transport API. This server provides tools to search for public transport stops and retrieve transit information using the General Transit Feed Specification (GTFS) format.
Features
- Stop Search: Search for Auckland Transport stops by name (case-insensitive substring match)
- Stop Trip Information: Retrieve scheduled trips and timetables for specific stops
- GTFS Integration: Uses General Transit Feed Specification for standardized transit data exchange
- FastMCP Framework: Built on FastMCP for easy MCP server development
- Type Safety: Full type hints and Pydantic models for data validation
Prerequisites
- Python >= 3.11
- uv package manager (recommended) or pip
- Auckland Transport API credentials
Installation
- Clone the repository:
git clone <repository-url>
cd auckland_transport
- Install dependencies using uv:
uv sync
Or using pip:
pip install -e .
Configuration
Create a .env file in the root directory with your Auckland Transport API credentials:
AT_BASE_URL=https://api.at.govt.nz/gtfs/v3
AT_API_KEY=your_api_key_here
Note: Make sure to add .env to your .gitignore file (already included) to keep your API keys secure.
Usage
Running the MCP Server
Start the MCP server:
python src/app.py
Testing
Run the test script to verify the connection:
python src/test.py
Using the Tools
The server provides the following MCP tools:
search_stop(name: str) -> StopResponse
Searches for Auckland Transport stops by name (case-insensitive substring match).
Parameters:
name(str): The stop name to search for
Returns:
StopResponse: A Pydantic model containing a list of matching stops with attributes including:stop_id: Unique identifier for the stopstop_code: Public-facing stop codestop_name: Name of the stopstop_lat: Latitude coordinatestop_lon: Longitude coordinatelocation_type: Type of location (0=stop, 1=station, etc.)wheelchair_boarding: Wheelchair accessibility information (0=unknown, 1=accessible, 2=not accessible)
Example:
from at_service import ATService
at_service = ATService()
result = at_service.search_stop("University")
print(result.model_dump_json())
get_stop_trips_by_stop_id(stop_id: str) -> StopTripResponse
Retrieves scheduled trips for a specific stop on the current date and hour.
Parameters:
stop_id(str): The unique identifier of the stop
Returns:
StopTripResponse: A Pydantic model containing a list of stop trips with attributes including:arrival_time: Scheduled arrival time (HH:MM:SS format)departure_time: Scheduled departure time (HH:MM:SS format)route_id: Identifier for the routetrip_headsign: Text displayed on the vehicle for this tripstop_headsign: Text displayed on signage at the stopstop_sequence: Order of this stop in the trip sequencedirection_id: Direction of travel (0 or 1)service_date: Date of service (YYYY-MM-DD format)shape_id: Identifier for the shape/geometry of the routepickup_type: Pickup type (0=regular, 1=none, 2=phone, 3=driver)drop_off_type: Drop-off type (0=regular, 1=none, 2=phone, 3=driver)
Example:
from at_service import ATService
at_service = ATService()
# First, search for a stop to get its stop_id
stops = at_service.search_stop("University")
if stops.data:
stop_id = stops.data[0].attributes.stop_id
trips = at_service.get_stop_trips_by_stop_id(stop_id)
print(trips.model_dump_json())
Project Structure
auckland-transport/
├── src/
│ ├── app.py # FastMCP server application with MCP tools
│ ├── at_service.py # Auckland Transport API service class
│ ├── gtfs_types.py # Pydantic models for GTFS data structures
│ ├── test.py # Test script for API connectivity
│ └── utils.py # Utility functions
├── .env # Environment variables (not in repo, create locally)
├── pyproject.toml # Project dependencies and metadata
├── uv.lock # Dependency lock file
└── README.md # This file
Dependencies
fastmcp>=2.13.2: FastMCP framework for building MCP serversdotenv>=0.9.9: Environment variable managementpydantic: Data validation and modeling for GTFS structuresrequests: HTTP library for API calls
Note: The project uses uv for dependency management. All dependencies are specified in pyproject.toml.
Development
Adding New Tools
To add new MCP tools, edit src/app.py and add new tool functions decorated with @mcp.tool:
@mcp.tool
def your_new_tool(param: str) -> ReturnType:
# Your implementation
return result
API Reference
The Auckland Transport API uses GTFS (General Transit Feed Specification) for data exchange. For more information about the API, visit the Auckland Transport API documentation.
Data Models
The project uses Pydantic models defined in gtfs_types.py to validate and structure API responses:
- StopAttributes: Contains stop location and accessibility information
- Stop: Represents a single stop resource with type, ID, and attributes
- StopResponse: Container for multiple stop search results
- StopTripAttributes: Contains trip timing, route, and service information
- StopTrip: Represents a single stop trip resource
- StopTripResponse: Container for multiple stop trip results
All models follow the GTFS standard and are fully typed for better IDE support and error checking.
Troubleshooting
Common Issues
-
API Key Not Found: Ensure your
.envfile exists in the root directory and contains bothAT_BASE_URLandAT_API_KEY. -
Empty Results: The API returns data for the current date and hour. If searching for trips, ensure there are scheduled services at the current time.
-
Connection Errors: Verify your internet connection and that the Auckland Transport API is accessible from your network.
References
- GTFS Static Overview - Google Developers - Official Google documentation for GTFS (General Transit Feed Specification)
- GTFS Documentation - gtfs.org - Official GTFS specification documentation maintained by MobilityData
License
MIT License
Copyright (c) 2025 Aira Technologies Limited
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.