idfm-mcp-server by HeshamWM - MCP Server

Î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

Tool	Status	Description
`get_next_departures`	✅ Working	Real-time departure times for specific stops
`get_traffic_info`	✅ Working	Service disruptions and network messages
`search_stops`	❌ Limited API	Stop search (API limitations explained)
`search_routes`	❌ Limited API	Journey planning (API limitations explained)
`get_line_info`	❌ Limited API	Line information (API limitations explained)

🚀 Quick Start

Prerequisites

Docker Desktop with MCP Toolkit enabled
IDFM PRIM API key from prim.iledefrance-mobilites.fr

Installation

Clone the repository

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

Set up your API key

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

Build the Docker image
```
docker build -t idfm-mcp-server .
```

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

Variable	Description	Default
`IDFM_API_KEY`	Direct API key (fallback)	Empty
`IDFM_API_KEY_FILE`	Path to API key file	Empty

🏗️ 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

Fork the repository
Create a feature branch
Make your changes
Test with real API data
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Resources

📞 Support

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

Built with ❤️ for the Paris public transport community