Skip to main content
This guide covers deploying the data.gouv.fr MCP server using Docker Compose. This is the recommended approach for production deployments.

​
Prerequisites

You need Docker installed on your system:
  • Docker Desktop (macOS, Windows, Linux)
  • Or any compatible Docker Engine with Docker Compose support

​
Quick Start

Clone the repository and navigate to the project directory: 
git clone [email protected]:datagouv/datagouv-mcp.git
cd datagouv-mcp

​
Basic Deployment

# Run with default settings (port 8000, prod environment)
docker compose up -d
The server will be available at http://localhost:8000/mcp (or your custom port).

​
Docker Compose Configuration

The docker-compose.yml file defines the service configuration:
docker-compose.yml
services:
  datagouv-mcp:
    build:
      context: .
      dockerfile: Dockerfile
    image: datagouv-mcp:latest
    ports:
      - "${MCP_PORT:-8000}:${MCP_PORT:-8000}"
    environment:
      - MCP_HOST=${MCP_HOST:-0.0.0.0}
      - MCP_PORT=${MCP_PORT:-8000}
      - DATAGOUV_API_ENV=${DATAGOUV_API_ENV:-prod}
      - MATOMO_SITE_ID=${MATOMO_SITE_ID}
      - MATOMO_AUTH_TOKEN=${MATOMO_AUTH_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import os, urllib.request; port = os.getenv('MCP_PORT', '8000'); urllib.request.urlopen(f'http://localhost:{port}/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

​
Key Configuration Points

  • Port mapping: The service exposes the port specified by MCP_PORT (default: 8000)
  • Host binding: Default is 0.0.0.0 to accept external connections in containerized environments
  • Auto-restart: The container restarts automatically unless explicitly stopped
  • Health checks: Built-in health monitoring using the /health endpoint

​
Environment Variables

You can customize the deployment by setting environment variables before running docker compose up: 
# Set variables inline
MCP_PORT=8007 DATAGOUV_API_ENV=demo docker compose up -d
See the Configuration page for detailed information about all available variables.

​
Production Deployment Considerations

​
Security

Never expose the MCP server directly to the internet without proper authentication and rate limiting.
  • Use a reverse proxy: Place the MCP server behind nginx or Caddy with proper authentication
  • Network isolation: Use Docker networks to isolate the MCP server from other services
  • TLS/SSL: Always use HTTPS in production with valid certificates

​
Monitoring

​
Health Check Endpoint

The server includes a built-in health check endpoint at /health: 
curl http://localhost:8000/health
Response: 
{
  "status": "ok",
  "timestamp": "2026-03-04T12:34:56.789Z",
  "version": "1.0.0"
}
The health check runs automatically every 30 seconds and Docker will restart the container if it fails 3 consecutive checks.

​
Sentry Integration

Enable error and performance monitoring with Sentry: 
SENTRY_DSN=https://your-sentry-dsn \
SENTRY_SAMPLE_RATE=0.1 \
MCP_ENV=prod \
docker compose up -d

​
Resource Limits

For production deployments, consider adding resource limits to your docker-compose.yml: 
services:
  datagouv-mcp:
    # ... existing configuration
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

​
Logging

View container logs: 
# Stream logs in real-time
docker compose logs -f
Adjust log verbosity with the LOG_LEVEL environment variable: 
LOG_LEVEL=DEBUG docker compose up -d

​
Updating the Server

To update to the latest version: 
# Pull latest changes
git pull origin main

# Rebuild and restart
docker compose down
docker compose build --no-cache
docker compose up -d

​
Troubleshooting

​
Container won’t start

Check the logs for errors: 
docker compose logs

​
Port conflicts

If port 8000 is already in use: 
MCP_PORT=8007 docker compose up -d

​
Health check failing

Verify the container can reach the health endpoint: 
docker compose exec datagouv-mcp curl http://localhost:8000/health

​
View container status

docker compose ps

Build docs developers (and LLMs) love

Get started for freeTalk to us