datagouv-mcp

Exposes the data.gouv.fr API v1 GET /1/datasets/ endpoint through an MCP tool that accepts free-text search queries and returns paginated dataset metadata (title, description, organization, tags, update frequency). Implements client-side pagination and result ranking to surface the most relevant datasets from France's national open data catalog without requiring users to manually navigate the web interface.

Fetches complete metadata for a single dataset by ID from data.gouv.fr API v1 GET /1/datasets/{id}/, returning title, description, organization, tags, creation/update timestamps, license, and a complete inventory of all associated resources (files). Uses a single API call per dataset to avoid N+1 queries and provides structured output suitable for downstream resource selection or analysis planning.

Provides a Dockerfile and Docker Compose configuration for containerized deployment, enabling the MCP server to run in Kubernetes, Docker Swarm, or any container orchestration platform. The container exposes port 8000 (HTTP) and includes health check configuration (GET /health endpoint) for orchestrator integration. Supports environment variable configuration for API endpoints, logging levels, and other runtime parameters, enabling deployment across development, staging, and production environments without code changes.

Centralizes all runtime configuration (API endpoints, logging levels, server port, CORS settings, etc.) in environment variables, enabling the same Docker image or Python process to run in different environments without code changes. Configuration is loaded at startup via a dedicated configuration module that validates and provides defaults. Supports multi-instance deployments where each instance can be configured independently via environment variables, enabling load-balanced and highly-available setups.

Queries data.gouv.fr API v2 GET /2/datasets/resources/{id}/ to retrieve detailed metadata for a single file/resource, including format (CSV, XLSX, JSON, etc.), file size, MIME type, and critically, whether the resource supports the Tabular API (a data.gouv.fr feature enabling row-level querying without full download). Returns structured metadata that allows agents to decide between streaming/parsing (for unsupported formats) or direct tabular queries (for supported formats).

Executes structured queries against CSV and XLSX resources using data.gouv.fr's Tabular API, supporting row filtering, column selection, sorting, and pagination. Implements client-side parameter validation and result streaming to handle large datasets within practical limits (respects data.gouv.fr rate limits and payload size constraints). Queries are executed without downloading the entire file, enabling efficient exploration of large datasets within a single conversation turn.

Downloads and parses CSV, XLSX, JSON, and other resource formats that do not support the Tabular API, streaming the file to avoid memory exhaustion and applying format-specific parsers (csv.DictReader for CSV, openpyxl for XLSX, json.load for JSON). Implements chunked reading and result truncation to respect practical limits on response size within MCP protocol constraints. Enables agents to access data from any format without requiring external download tools.

Queries data.gouv.fr's dataservice catalog (API endpoints, web services, and data APIs exposed by organizations) via dedicated MCP tools that search and retrieve dataservice metadata. Enables agents to discover and understand available APIs and services without manual catalog browsing, returning service descriptions, endpoints, and usage documentation. Complements dataset discovery by surfacing programmatic access methods.

Exposes a dedicated MCP tool that retrieves aggregate metrics about the data.gouv.fr platform, including total dataset count, organization count, resource count, and platform-wide usage statistics. Provides agents with context about the scale and activity of the platform without requiring manual inspection of the website. Useful for generating summaries or understanding data availability trends.

Implements the Model Context Protocol (MCP) server specification using FastMCP framework with Streamable HTTP transport (POST /mcp endpoint), enabling any MCP-compatible client (ChatGPT, Claude Desktop, Gemini, Cursor, VS Code, etc.) to invoke data.gouv.fr tools through a standardized interface. Handles MCP request/response serialization, tool schema registration, and error handling transparently. The server exposes exactly two HTTP endpoints: /mcp for tool invocation and /health for liveness probes.

Organizes the codebase into three strictly separated layers with one-way dependency flow: main.py (entry point and ASGI middleware) → tools/ (MCP tool implementations) → helpers/ (external API clients). Each layer has a single responsibility: entry point creates the FastMCP instance and runs uvicorn; tools implement MCP tool logic; helpers wrap external HTTP APIs with typed async functions. This architecture enables independent testing, easy addition of new tools, and clear separation between protocol handling and business logic.

Implements a single shared logger named 'datagouv_mcp' created in main.py and referenced by name across all modules, providing centralized log aggregation and debugging. Logs are emitted at appropriate levels (DEBUG for API calls, INFO for tool invocations, ERROR for failures) and can be redirected to stdout, files, or external logging services via standard Python logging configuration. Enables operators to monitor server health and troubleshoot issues without instrumenting individual modules.