# Idfm Mcp Server

> MCP Server for Paris public transport data - Real-time departures, traffic info via IDFM PRIM API. Docker-based with Claude Desktop integration.

- **Type:** MCP server
- **Install:** `agentstack add mcp-heshamwm-idfm-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HeshamWM](https://agentstack.voostack.com/s/heshamwm)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HeshamWM](https://github.com/HeshamWM)
- **Source:** https://github.com/HeshamWM/idfm-mcp-server

## Install

```sh
agentstack add mcp-heshamwm-idfm-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Î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](https://prim.iledefrance-mobilites.fr/)

### Installation

1. **Clone the repository**
   ```bash
   git clone 
   cd idfm-mcp-server
   ```

2. **Set up your API key**
   ```bash
   docker mcp secret set IDFM_API_KEY=your-api-key-here
   ```

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

4. **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

```json
{
  "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:

```bash
# 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](https://prim.iledefrance-mobilites.fr/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Docker MCP Toolkit Documentation](https://docs.docker.com/desktop/mcp/)
- [Île-de-France Mobilités](https://www.iledefrance-mobilites.fr/)

## 📞 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](https://github.com/HeshamWM)
- **Source:** [HeshamWM/idfm-mcp-server](https://github.com/HeshamWM/idfm-mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-heshamwm-idfm-mcp-server
- Seller: https://agentstack.voostack.com/s/heshamwm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.