Île-de-France Mobilités MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to real-time Paris public transport data through the IDFM PRIM API.

🚇 Overview

This Docker-based MCP server enables AI assistants like Claude to access live information about the Paris public transport network (métro, RER, bus, tram, Transilien trains) managed by Île-de-France Mobilités.

Key Features

• Real-time Departures: Get next departure times for any transport stop

• Traffic Disruptions: Monitor service alerts and disruptions across the network

• Docker Integration: Runs as a containerized MCP server with Docker Desktop

• Secure API Management: Uses Docker MCP Toolkit's secret management

• SIRI Protocol Support: Compatible with the official IDFM PRIM API

🛠️ Technologies

• Python 3.11 with FastMCP framework

• Docker containerization with multi-stage builds

• SIRI (Service Interface for Real Time Information) protocol

• HTTPX for async HTTP requests

• Model Context Protocol for AI assistant integration

📋 Available Tools

🚀 Quick Start

Prerequisites

• Docker Desktop with MCP Toolkit enabled

• IDFM PRIM API key from prim.iledefrance-mobilites.fr

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd idfm-mcp-server

2. Set up your API key

   docker mcp secret set IDFM_API_KEY=your-api-key-here

3. Build the Docker image

   docker build -t idfm-mcp-server .

4. Test the server

   echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | \
   docker run --rm -i -l x-secret:IDFM_API_KEY=/tmp/api_key.txt -e IDFM_API_KEY_FILE=/tmp/api_key.txt idfm-mcp-server

💡 Usage Examples

With Claude Desktop

Ask natural language questions like:

• "What are the next trains at Châtelet station?"

• "Are there any disruptions on the RER A line?"

• "Show me departure times for stop STIF:StopPoint:Q:41304:"

Direct API Calls

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_next_departures",
    "arguments": {
      "stop_id": "STIF:StopPoint:Q:41304:",
      "max_results": "5"
    }
  },
  "id": 1
}

🔧 Configuration

Docker MCP Secrets

The server reads the API key from Docker MCP secrets:

# Set the secret
docker mcp secret set IDFM_API_KEY=your-key-here

# Run with secret mounting
docker run -l x-secret:IDFM_API_KEY=/tmp/api_key.txt -e IDFM_API_KEY_FILE=/tmp/api_key.txt idfm-mcp-server

Environment Variables

🏗️ Architecture

Claude Desktop → MCP Protocol → Docker Container → IDFM PRIM API
                      ↓
              Docker MCP Secrets

The server implements the MCP protocol to provide a secure, standardized interface between AI assistants and the IDFM transport data.

📊 API Limitations

The IDFM PRIM API has evolved and currently supports:

• ✅ SIRI Protocol: Real-time monitoring and disruption data

• ❌ NavItia Protocol: Historical search endpoints have been deprecated

This server provides honest error messages explaining these limitations and suggests alternatives for unavailable functionality.

🔒 Security

• API keys stored securely in Docker MCP secrets

• Non-root user execution in container

• No API key logging or exposure

• Rate limiting awareness (1M requests/day for monitoring)

🐛 Troubleshooting

Common Issues

Tools not appearing in Claude:

• Verify Docker image built successfully: docker images | grep idfm

• Check MCP server registration

• Restart Claude Desktop

Authentication errors:

• Verify secret: docker mcp secret ls

• Ensure API key is valid at PRIM portal

• Check container has secret access

No departure data:

• Verify stop ID format (use SIRI format: STIF:StopPoint:Q:XXXXX:)

• Some stops may not have real-time data

• Check service schedules (reduced on weekends/holidays)

Stop ID Formats

The API requires specific SIRI-compliant stop IDs:

• ✅ STIF:StopPoint:Q:41304: (Châtelet-Les Halles)

• ❌ stop_area:IDFM:71571 (Old NavItia format)

📈 Rate Limits

• Stop Monitoring: 1,000,000 requests/day

• General Access: 20,000 requests/day

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test with real API data

5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Resources

• IDFM PRIM API Portal

• Model Context Protocol Specification

• Docker MCP Toolkit Documentation

• Île-de-France Mobilités

📞 Support

For API-related issues, contact IDFM support. For server issues, please open a GitHub issue.

Built with ❤️ for the Paris public transport community