Idfm 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

1. Clone the repository

``bash git clone cd idfm-mcp-server ``

1. Set up your API key

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

1. Build the Docker image

``bash docker build -t idfm-mcp-server . ``

1. Test the server

``bash 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

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HeshamWM
• Source: HeshamWM/idfm-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.