# datagouv/datagouv-mcp architecture

> Architecture diagram of the GitHub repository datagouv/datagouv-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datagouv/datagouv-mcp
- Repository: https://github.com/datagouv/datagouv-mcp

## Overview

This is a Python MCP server that lets chatbots search and inspect the data.gouv.fr open-data catalog, retrieve resource data, and explore registered third-party APIs. The principal workflow is chatbot request → registered MCP tool → catalog or data-service client → formatted result. Tools cover dataset and organization discovery, dataset/resource details, tabular queries, metrics, and third-party API specifications. The graph also shows supporting API clients, health/telemetry, and configuration. Some tool and server behavior is known only from the README or source index; those links are cited accordingly.

Main entry points: [`helpers/datagouv_api_client.py`](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/datagouv_api_client.py) (Catalog API client), [`tools/__init__.py`](https://github.com/datagouv/datagouv-mcp/blob/main/tools/__init__.py) (Tool registry), [`main.py`](https://github.com/datagouv/datagouv-mcp/blob/main/main.py) (MCP entrypoint), [`helpers/logging.py`](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/logging.py) (Tool logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_server["MCP entrypoint<br/>[main.py]"]
  node_registry["Tool registry<br/>[__init__.py]"]
end

subgraph group_discovery["Catalog discovery"]
  node_search_datasets["Search datasets<br/>[search_datasets.py]"]
  node_search_orgs["Search organizations"]
  node_search_services["Search APIs"]
  node_dataset_info["Dataset details"]
  node_resource_list["List resources"]
  node_resource_info["Resource details"]
  node_service_info["API details"]
  node_openapi["API specification"]
end

subgraph group_analysis["Data exploration"]
  node_query_data["Query tabular data"]
  node_metrics_tool["Metrics tool<br/>[get_metrics.py]"]
end

subgraph group_support["Clients and operations"]
  node_catalog_client["Catalog API client"]
  node_crawler_client["Crawler API client"]
  node_tabular_client["Tabular API client"]
  node_metrics_client["Metrics API client"]
  node_env_config["Endpoint configuration<br/>[env_config.py]"]
  node_ssrf["SSRF safeguards<br/>[ssrf.py]"]
  node_health["Health probe<br/>[health_probe.py]"]
  node_logging["Tool logging<br/>[logging.py]"]
  node_matomo["Usage analytics<br/>[matomo.py]"]
  node_defaults["Tool defaults"]
  node_user_agent["Service identity<br/>[user_agent.py]"]
end

node_chatbot(("Chatbot client"))
node_datagouv{{"data.gouv.fr APIs"}}
node_crawler{{"Crawler service"}}
node_tabular{{"Tabular service"}}
node_metrics{{"Metrics service"}}
node_matomo_service{{"Matomo"}}

node_chatbot -->|"requests tools"| node_server
node_server -->|"registers tools"| node_registry
node_server -->|"uses probe"| node_health
node_server -->|"uses logging"| node_logging
node_server -->|"sets context"| node_matomo
node_registry -->|"registers"| node_search_datasets
node_registry -->|"registers"| node_search_orgs
node_registry -->|"registers"| node_search_services
node_registry -->|"registers"| node_dataset_info
node_registry -->|"registers"| node_resource_list
node_registry -->|"registers"| node_resource_info
node_registry -->|"registers"| node_service_info
node_registry -->|"registers"| node_openapi
node_registry -->|"registers"| node_query_data
node_registry -->|"registers"| node_metrics_tool
node_search_datasets -->|"queries catalog"| node_catalog_client
node_search_orgs -->|"queries catalog"| node_catalog_client
node_search_services -->|"queries catalog"| node_catalog_client
node_dataset_info -->|"fetches details"| node_catalog_client
node_resource_list -->|"fetches resources"| node_catalog_client
node_resource_info -->|"fetches metadata"| node_catalog_client
node_resource_info -->|"checks resource"| node_crawler_client
node_service_info -->|"fetches details"| node_catalog_client
node_openapi -->|"fetches specification"| node_catalog_client
node_openapi -->|"validates URL"| node_ssrf
node_query_data -->|"fetches metadata"| node_catalog_client
node_query_data -->|"queries rows"| node_tabular_client
node_metrics_tool -->|"fetches catalog data"| node_catalog_client
node_metrics_tool -->|"fetches metrics"| node_metrics_client
node_catalog_client -->|"calls API"| node_datagouv
node_crawler_client -->|"calls API"| node_crawler
node_tabular_client -->|"calls API"| node_tabular
node_metrics_client -->|"calls API"| node_metrics
node_catalog_client -->|"gets endpoints"| node_env_config
node_crawler_client -->|"gets endpoints"| node_env_config
node_tabular_client -->|"gets endpoints"| node_env_config
node_metrics_client -->|"gets endpoints"| node_env_config
node_catalog_client -->|"sets identity"| node_user_agent
node_crawler_client -->|"sets identity"| node_user_agent
node_tabular_client -->|"sets identity"| node_user_agent
node_metrics_client -->|"sets identity"| node_user_agent
node_search_datasets -->|"logs calls"| node_logging
node_search_services -->|"logs calls"| node_logging
node_query_data -->|"logs calls"| node_logging
node_search_datasets -->|"declares behavior"| node_defaults
node_openapi -->|"declares behavior"| node_defaults
node_logging -->|"tracks events"| node_matomo
node_matomo -->|"posts events"| node_matomo_service

click node_server "https://github.com/datagouv/datagouv-mcp/blob/main/main.py"
click node_registry "https://github.com/datagouv/datagouv-mcp/blob/main/tools/__init__.py"
click node_search_datasets "https://github.com/datagouv/datagouv-mcp/blob/main/tools/search_datasets.py"
click node_search_orgs "https://github.com/datagouv/datagouv-mcp/blob/main/tools/search_organizations.py"
click node_search_services "https://github.com/datagouv/datagouv-mcp/blob/main/tools/search_dataservices.py"
click node_dataset_info "https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_dataset_info.py"
click node_resource_list "https://github.com/datagouv/datagouv-mcp/blob/main/tools/list_dataset_resources.py"
click node_resource_info "https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_resource_info.py"
click node_service_info "https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_dataservice_info.py"
click node_openapi "https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_dataservice_openapi_spec.py"
click node_query_data "https://github.com/datagouv/datagouv-mcp/blob/main/tools/query_resource_data.py"
click node_metrics_tool "https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_metrics.py"
click node_catalog_client "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/datagouv_api_client.py"
click node_crawler_client "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/crawler_api_client.py"
click node_tabular_client "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/tabular_api_client.py"
click node_metrics_client "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/metrics_api_client.py"
click node_env_config "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/env_config.py"
click node_ssrf "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/ssrf.py"
click node_health "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/health_probe.py"
click node_logging "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/logging.py"
click node_matomo "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/matomo.py"
click node_defaults "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/mcp_tool_defaults.py"
click node_user_agent "https://github.com/datagouv/datagouv-mcp/blob/main/helpers/user_agent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_registry,node_chatbot toneBlue
class node_search_datasets,node_search_orgs,node_search_services,node_dataset_info,node_resource_list,node_resource_info,node_service_info,node_openapi toneAmber
class node_query_data,node_metrics_tool,node_datagouv toneMint
class node_catalog_client,node_crawler_client,node_tabular_client,node_metrics_client,node_env_config,node_ssrf,node_health,node_logging,node_matomo,node_defaults,node_user_agent toneRose
class node_crawler,node_tabular,node_metrics,node_matomo_service toneIndigo
```

## Components

### MCP server

- [MCP entrypoint](https://github.com/datagouv/datagouv-mcp/blob/main/main.py): `main.py`
- [Tool registry](https://github.com/datagouv/datagouv-mcp/blob/main/tools/__init__.py): `tools/__init__.py`

### Catalog discovery

- [Search datasets](https://github.com/datagouv/datagouv-mcp/blob/main/tools/search_datasets.py): `tools/search_datasets.py`
- [Search organizations](https://github.com/datagouv/datagouv-mcp/blob/main/tools/search_organizations.py): `tools/search_organizations.py`
- [Search APIs](https://github.com/datagouv/datagouv-mcp/blob/main/tools/search_dataservices.py): `tools/search_dataservices.py`
- [Dataset details](https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_dataset_info.py): `tools/get_dataset_info.py`
- [List resources](https://github.com/datagouv/datagouv-mcp/blob/main/tools/list_dataset_resources.py): `tools/list_dataset_resources.py`
- [Resource details](https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_resource_info.py): `tools/get_resource_info.py`
- [API details](https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_dataservice_info.py): `tools/get_dataservice_info.py`
- [API specification](https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_dataservice_openapi_spec.py): `tools/get_dataservice_openapi_spec.py`

### Data exploration

- [Query tabular data](https://github.com/datagouv/datagouv-mcp/blob/main/tools/query_resource_data.py): `tools/query_resource_data.py`
- [Metrics tool](https://github.com/datagouv/datagouv-mcp/blob/main/tools/get_metrics.py): `tools/get_metrics.py`

### Clients and operations

- [Catalog API client](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/datagouv_api_client.py): `helpers/datagouv_api_client.py`
- [Crawler API client](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/crawler_api_client.py): `helpers/crawler_api_client.py`
- [Tabular API client](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/tabular_api_client.py): `helpers/tabular_api_client.py`
- [Metrics API client](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/metrics_api_client.py): `helpers/metrics_api_client.py`
- [Endpoint configuration](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/env_config.py): `helpers/env_config.py`
- [SSRF safeguards](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/ssrf.py): `helpers/ssrf.py`
- [Health probe](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/health_probe.py): `helpers/health_probe.py`
- [Tool logging](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/logging.py): `helpers/logging.py`
- [Usage analytics](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/matomo.py): `helpers/matomo.py`
- [Tool defaults](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/mcp_tool_defaults.py): `helpers/mcp_tool_defaults.py`
- [Service identity](https://github.com/datagouv/datagouv-mcp/blob/main/helpers/user_agent.py): `helpers/user_agent.py`

### Other components

- **Chatbot client**
- **data.gouv.fr APIs**
- **Crawler service**
- **Tabular service**
- **Metrics service**
- **Matomo**

## Connections

- Chatbot client → MCP entrypoint: requests tools (evidence: `README.md`)
- MCP entrypoint → Tool registry: registers tools (evidence: `main.py`)
- MCP entrypoint → Health probe: uses probe (evidence: `main.py`)
- MCP entrypoint → Tool logging: uses logging (evidence: `main.py`)
- MCP entrypoint → Usage analytics: sets context (evidence: `main.py`)
- Tool registry → Search datasets: registers (evidence: `tools/__init__.py`)
- Tool registry → Search organizations: registers (evidence: `tools/__init__.py`)
- Tool registry → Search APIs: registers (evidence: `tools/__init__.py`)
- Tool registry → Dataset details: registers (evidence: `tools/__init__.py`)
- Tool registry → List resources: registers (evidence: `tools/__init__.py`)
- Tool registry → Resource details: registers (evidence: `tools/__init__.py`)
- Tool registry → API details: registers (evidence: `tools/__init__.py`)
- Tool registry → API specification: registers (evidence: `tools/__init__.py`)
- Tool registry → Query tabular data: registers (evidence: `tools/__init__.py`)
- Tool registry → Metrics tool: registers (evidence: `tools/__init__.py`)
- Search datasets → Catalog API client: queries catalog (evidence: `tools/search_datasets.py`)
- Search organizations → Catalog API client: queries catalog (evidence: `tools/search_organizations.py`)
- Search APIs → Catalog API client: queries catalog (evidence: `tools/search_dataservices.py`)
- Dataset details → Catalog API client: fetches details (evidence: `tools/get_dataset_info.py`)
- List resources → Catalog API client: fetches resources (evidence: `tools/list_dataset_resources.py`)
- Resource details → Catalog API client: fetches metadata (evidence: `tools/get_resource_info.py`)
- Resource details → Crawler API client: checks resource (evidence: `tools/get_resource_info.py`)
- API details → Catalog API client: fetches details (evidence: `tools/get_dataservice_info.py`)
- API specification → Catalog API client: fetches specification (evidence: `tools/get_dataservice_openapi_spec.py`)
- API specification → SSRF safeguards: validates URL (evidence: `tools/get_dataservice_openapi_spec.py`)
- Query tabular data → Catalog API client: fetches metadata (evidence: `tools/query_resource_data.py`)
- Query tabular data → Tabular API client: queries rows (evidence: `tools/query_resource_data.py`)
- Metrics tool → Catalog API client: fetches catalog data (evidence: `tools/get_metrics.py`)
- Metrics tool → Metrics API client: fetches metrics (evidence: `tools/get_metrics.py`)
- Catalog API client → data.gouv.fr APIs: calls API (evidence: `helpers/datagouv_api_client.py`)
- Crawler API client → Crawler service: calls API (evidence: `helpers/crawler_api_client.py`)
- Tabular API client → Tabular service: calls API (evidence: `helpers/tabular_api_client.py`)
- Metrics API client → Metrics service: calls API (evidence: `helpers/metrics_api_client.py`)
- Catalog API client → Endpoint configuration: gets endpoints (evidence: `helpers/datagouv_api_client.py`)
- Crawler API client → Endpoint configuration: gets endpoints (evidence: `helpers/crawler_api_client.py`)
- Tabular API client → Endpoint configuration: gets endpoints (evidence: `helpers/tabular_api_client.py`)
- Metrics API client → Endpoint configuration: gets endpoints (evidence: `helpers/metrics_api_client.py`)
- Catalog API client → Service identity: sets identity (evidence: `helpers/datagouv_api_client.py`)
- Crawler API client → Service identity: sets identity (evidence: `helpers/crawler_api_client.py`)
- Tabular API client → Service identity: sets identity (evidence: `helpers/tabular_api_client.py`)
- Metrics API client → Service identity: sets identity (evidence: `helpers/metrics_api_client.py`)
- Search datasets → Tool logging: logs calls (evidence: `tools/search_datasets.py`)
- Search APIs → Tool logging: logs calls (evidence: `tools/search_dataservices.py`)
- Query tabular data → Tool logging: logs calls (evidence: `tools/query_resource_data.py`)
- Search datasets → Tool defaults: declares behavior (evidence: `tools/search_datasets.py`)
- API specification → Tool defaults: declares behavior (evidence: `tools/get_dataservice_openapi_spec.py`)
- Tool logging → Usage analytics: tracks events (evidence: `helpers/logging.py`)
- Usage analytics → Matomo: posts events (evidence: `helpers/matomo.py`)
