datagouv/datagouv-mcp
GitHub: datagouv/datagouv-mcp
法国国家开放数据平台的官方 MCP 服务器，让 AI 聊天机器人能够直接通过对话搜索和分析政府开放数据集。
Stars: 951 | Forks: 77
# data.gouv.fr MCP Server
[](https://circleci.com/gh/datagouv/datagouv-mcp)
[](https://opensource.org/licenses/MIT)
Model Context Protocol (MCP) server，允许 AI 聊天机器人（Claude、ChatGPT、Gemini 等）直接通过对话搜索、探索和分析来自 [data.gouv.fr](https://www.data.gouv.fr)（法国国家开放数据平台）的数据集。
无需手动浏览网站，您只需提问，例如“Quels jeux de données sont disponibles sur les prix de l'immobilier ?”或“Montre-moi les dernières données de population pour Paris”，即可获得即时答案。
## 🌐 将聊天机器人连接到 MCP Server
使用托管端点 `https://mcp.data.gouv.fr/mcp`（推荐）。如果您是自托管，请替换为您自己的 URL。
MCP Server 配置取决于您的客户端。请为您的客户端使用适当的配置格式：
[AnythingLLM](#anythingllm) | [ChatGPT](#chatgpt) | [Claude Code](#claude-code) | [Claude Desktop](#claude-desktop) | [Cursor](#cursor) | [Gemini CLI](#gemini-cli) | [HuggingChat](#huggingchat) | [IBM Bob](#ibm-bob) | [Kiro CLI](#kiro-cli) | [Kiro IDE](#kiro-ide) | [Le Chat (Mistral)](#le-chat-mistral) | [Mistral Vibe](#mistral-vibe-cli) | [VS Code](#vs-code) | [Windsurf](#windsurf)
### AnythingLLM
1. 在您的 AnythingLLM 存储 plugins 目录中找到 `anythingllm_mcp_servers.json` 文件：
- **Linux**: `~/.config/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json`
- **MacOS**: `~/Library/Application Support/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json`
- **Windows**: `C:\Users\\AppData\Roaming\anythingllm-desktop\storage\plugins\anythingllm_mcp_servers.json`
2. 添加以下配置：
```
{
"mcpServers": {
"datagouv": {
"type": "streamable",
"url": "https://mcp.data.gouv.fr/mcp"
}
}
}
```
有关更多详细信息，请参阅 [AnythingLLM MCP 文档](https://docs.anythingllm.com/mcp-compatibility/overview)。
### ChatGPT
*仅适用于付费计划（Plus、Pro、Team 和 Enterprise）。*
1. **访问设置**：在浏览器中打开 ChatGPT，转到 `Settings`，然后转到 `Apps and connectors`。
2. **启用开发者模式**：打开 `Advanced settings` 并启用 **Developer mode**。
3. **添加连接器**：返回 `Settings` > `Connectors` > `Browse connectors` 并点击 **Add a new connector**。
4. **配置连接器**：将 URL 设置为 `https://mcp.data.gouv.fr/mcp` 并保存以激活工具。
### Claude Code
使用 `claude mcp` 命令添加 MCP Server：
```
claude mcp add --transport http datagouv https://mcp.data.gouv.fr/mcp
```
### Claude Desktop
将以下内容添加到您的 Claude Desktop 配置文件中（通常 Linux 上为 `~/.config/Claude/claude_desktop_config.json`，MacOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`，或 Windows 上为 `%APPDATA%\Claude\claude_desktop_config.json`）：
```
{
"mcpServers": {
"datagouv": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.data.gouv.fr/mcp"
]
}
}
}
```
### Cursor
Cursor 通过其设置支持 MCP Server。要配置服务器：
1. 打开 Cursor 设置
2. 搜索“MCP”或“Model Context Protocol”
3. 使用以下配置添加新的 MCP Server：
```
{
"mcpServers": {
"datagouv": {
"url": "https://mcp.data.gouv.fr/mcp",
"transport": "http"
}
}
}
```
### Gemini CLI
将以下内容添加到您的 `~/.gemini/settings.json` 文件中（Linux: `~/.gemini/settings.json`，MacOS: `~/.gemini/settings.json`，Windows: `%USERPROFILE%\.gemini\settings.json`）：
```
{
"mcpServers": {
"datagouv": {
"httpUrl": "https://mcp.data.gouv.fr/mcp"
}
}
}
```
### HuggingChat
1. **访问设置**：在聊天界面中，点击 + 图标，选择 `MCP Servers`，然后点击 `Manage MCP Servers`。
2. **添加服务器**：在服务器管理窗口中点击 + `Add Server` 按钮。
3. **配置服务器**：输入 **Server Name**（例如“Data Gouv”）并将 **Server URL** 设置为 `https://mcp.data.gouv.fr/mcp`。点击 `Add Server` 保存。
4. **验证连接**：点击新服务器卡片上的 `Health Check` 按钮以确认其显示为 **Connected**。确保开关已激活以便在聊天中使用工具。
### IBM Bob
IBM Bob 通过其设置支持 MCP Server。要配置服务器：
1. 点击 Bob 面板中的设置图标。
2. 选择 MCP 选项卡。
3. 点击相应的按钮：
- Edit Global MCP：打开全局 `mcp_settings.json` 文件
- Edit Project MCP：打开项目特定的 `.bob/mcp.json` 文件（如果不存在，Bob 会创建它）
这两个文件都使用 JSON 格式，其中包含命名服务器配置的 mcpServers 对象。
```
{
"mcpServers": {
"datagouv": {
"url": "https://mcp.data.gouv.fr/mcp",
"type": "streamable-http"
}
}
}
```
### Kiro CLI
将以下内容添加到 `~/.kiro/settings/mcp.json`（Linux: `~/.kiro/settings/mcp.json`，MacOS: `~/.kiro/settings/mcp.json`，Windows: `%USERPROFILE%\.kiro\settings\mcp.json`）：
```
{
"mcpServers": {
"datagouv": {
"url": "https://mcp.data.gouv.fr/mcp"
}
}
}
```
### Kiro IDE
将以下内容添加到您的 Kiro MCP 配置文件中（工作区中的 `.kiro/settings/mcp.json`，或对于全局配置：Linux: `~/.kiro/settings/mcp.json`，MacOS: `~/.kiro/settings/mcp.json`，Windows: `%USERPROFILE%\.kiro\settings\mcp.json`）：
```
{
"mcpServers": {
"datagouv": {
"url": "https://mcp.data.gouv.fr/mcp"
}
}
}
```
### Le Chat (Mistral)
*适用于所有计划，包括免费计划。*
1. **转到连接器**：在浏览器中打开 Mistral，然后转到 `Intelligence` > `Connectors`。
2. **添加自定义连接器**：点击 `Add connector` > `Custom MCP Connector`，为其命名（例如 `DataGouv`），并将服务器 URL 设置为 `https://mcp.data.gouv.fr/mcp`。
3. **无需认证**：保持认证禁用状态。
4. **创建**：点击 **Create**。
### Mistral Vibe CLI
编辑您的 Vibe 配置（默认：Linux: `~/.vibe/config.toml`，MacOS: `~/.vibe/config.toml`，Windows: `%USERPROFILE%\.vibe\config.toml`）并添加 MCP Server：
```
[[mcp_servers]]
name = "datagouv"
transport = "streamable-http"
url = "https://mcp.data.gouv.fr/mcp"
```
请在官方文档中查看完整的 Vibe MCP 选项：[MCP Server 配置](https://github.com/mistralai/mistral-vibe?tab=readme-ov-file#mcp-server-configuration)。
### VS Code
将以下内容添加到您的 VS Code `mcp.json` 文件中（Linux: `~/.config/Code/User/mcp.json`，MacOS: `~/Library/Application Support/Code/User/mcp.json`，Windows: `%APPDATA%\Code\User\mcp.json`）。从命令面板运行 **MCP: Open User Configuration** 以打开它。
```
{
"servers": {
"datagouv": {
"url": "https://mcp.data.gouv.fr/mcp",
"type": "http"
}
}
}
```
### Windsurf
将以下内容添加到您的 `~/.codeium/windsurf/mcp_config.json` 中（Linux: `~/.codeium/windsurf/mcp_config.json`，MacOS: `~/.codeium/windsurf/mcp_config.json`，Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`）：
```
{
"mcpServers": {
"datagouv": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.data.gouv.fr/mcp"
]
}
}
}
```
**注意：**
- 托管端点为 `https://mcp.data.gouv.fr/mcp`。如果您自行运行服务器，请将其替换为您自己的 URL（有关默认本地端点，请参见下方的“本地运行”）。
- 此 MCP Server 目前仅公开只读工具，因此不需要 API 密钥。
## 🖥️ 本地运行
### 1. 运行 MCP Server
在开始之前，请克隆此仓库并进入该目录：
```
git clone git@github.com:datagouv/datagouv-mcp.git
cd datagouv-mcp
```
推荐的设置需要 Docker。在继续之前，请通过 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 或任何兼容的 Docker Engine 安装它。
#### 🐳 使用 Docker（推荐）
```
# 使用默认设置（端口 8000，prod 环境）
docker compose up -d
# 使用自定义环境变量
MCP_PORT=8007 DATAGOUV_API_ENV=demo LOG_LEVEL=DEBUG docker compose up -d
# 停止
docker compose down
```
**环境变量：**
- `MCP_HOST`：要绑定到的主机（默认为 `0.0.0.0`）。对于本地开发，设置为 `127.0.0.1` 以遵循 MCP 安全最佳实践。
- `MCP_PORT`：MCP HTTP 服务器的端口（未设置时默认为 `8000`）。
- `MCP_ENV`：报告给 Sentry 的环境名称（未设置时默认为 `local`）。在您的部署中显式设置为 `prod`、`preprod` 或 `demo`。
- `DATAGOUV_API_ENV`：`prod`（默认）或 `demo`。这控制它使用 data.gouv.fr 的哪个环境的数据（https://www.data.gouv.fr 或 https://demo.data.gouv.fr）。默认情况下，MCP Server 与生产环境的 data.gouv.fr 通信。如果您特别需要演示环境，请设置 `DATAGOUV_API_ENV=demo`。
- `LOG_LEVEL`：应用程序的 Python logging 级别（默认为 `INFO`）。常用值：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`。
- `SENTRY_DSN`：用于启用错误和性能监控的 Sentry DSN。未设置时禁用监控。
- `SENTRY_SAMPLE_RATE`：Sentry traces 和 profiles 的采样率（浮点数 `0.0`–`1.0`，默认为 `1.0`）。
#### ⚙️ 手动安装
您需要 [uv](https://github.com/astral-sh/uv) 来安装依赖项并运行服务器。
1. **安装依赖项**
```
uv sync
```
2. **准备环境文件**
复制[示例环境文件](.env.example)以创建您自己的 `.env` 文件：
```
cp .env.example .env
```
然后可选地编辑 `.env` 并设置对您的运行重要的变量：
```
MCP_HOST=127.0.0.1 # (defaults to 0.0.0.0, use 127.0.0.1 for local dev)
MCP_PORT=8007 # (defaults to 8000 when unset)
MCP_ENV=local # environment name sent to Sentry (defaults to local when unset)
DATAGOUV_API_ENV=prod # Allowed values: demo | prod (defaults to prod when unset)
LOG_LEVEL=INFO # Python log level (default: INFO)
```
使用您喜欢的方法加载变量，例如：
```
set -a && source .env && set +a
```
3. **启动 HTTP MCP Server**
```
uv run main.py
```
### 2. 将聊天机器人连接到本地 MCP Server
按照[将聊天机器人连接到 MCP Server](#-connect-your-chatbot-to-the-mcp-server)中的步骤操作，只需将托管 URL 替换为您的本地端点（默认：`http://127.0.0.1:${MCP_PORT:-8000}/mcp`）。
## 🚚 传输支持
MCP Server 使用 [MCP Server 和客户端官方 Python SDK](https://github.com/modelcontextprotocol/python-sdk) 构建，并**仅使用 Streamable HTTP 传输**。
**不支持 STDIO 和 SSE**。
## 📋 可用端点
**Streamable HTTP 传输（符合标准）：**
- `POST /mcp` - JSON-RPC 消息（客户端 → 服务器）
- `GET /health` - 简单的 JSON 健康检查（`{"status":"ok","timestamp":"..."}`）
## 🛠️ 可用工具
MCP Server 提供与 data.gouv.fr 数据集和数据服务交互的工具。
**注意：**“Dataservices”是注册在 data.gouv.fr 目录中的外部第三方 API（例如 Adresse API、Sirene API）。它们与 data.gouv.fr 自己的内部 API（Main/Tabular/Metrics）不同，后者为此 MCP Server 提供支持。
### Datasets（静态数据文件）
- **`search_datasets`** - 按关键词搜索数据集。返回带有元数据（标题、描述、组织、标签、资源数量）的数据集。
参数：`query`（必需），`page`（可选，默认：1），`page_size`（可选，默认：20，最大：100）
- **`get_dataset_info`** - 获取有关特定数据集的详细信息（元数据、组织、标签、日期、许可证等）。
参数：`dataset_id`（必需）
- **`list_dataset_resources`** - 列出数据集中的所有资源（文件）及其元数据（格式、大小、类型、URL）。
参数：`dataset_id`（必需）
- **`get_resource_info`** - 获取有关特定资源的详细信息（格式、大小、MIME 类型、URL、数据集关联、Tabular API 可用性）。
参数：`resource_id`（必需）
- **`query_resource_data`** - 通过 Tabular API 查询特定资源的数据。从资源中获取行以回答问题。
参数：`question`（必需），`resource_id`（必需），`page`（可选，默认：1），`page_size`（可选，默认：20，最大：200）
注意：推荐的工作流程：1) 使用 `search_datasets` 查找数据集，2) 使用 `list_dataset_resources` 查看可用资源，3) 使用默认 `page_size`（20）的 `query_resource_data` 预览数据结构。对于小型数据集（<500 行），增加 `page_size` 或进行分页。对于大型数据集（>1000 行），继续分页或使用 `get_resource_info` 检索原始文件 URL 并直接获取它。适用于 Tabular API 大小内的 CSV/XLS 资源（CSV ≤ 100 MB，XLSX ≤ 12.5 MB）。
### Dataservices（外部 API）
- **`search_dataservices`** - 按关键词搜索注册在 data.gouv.fr 上的数据服务（API）。返回带有元数据（标题、描述、组织、基础 API URL、标签）的数据服务。
参数：`query`（必需），`page`（可选，默认：1），`page_size`（可选，默认：20，最大：100）
- **`get_dataservice_info`** - 获取有关特定数据服务的详细元数据（标题、描述、组织、基础 API URL、OpenAPI spec URL、许可证、日期、相关数据集）。
参数：`dataservice_id`（必需）
- **`get_dataservice_openapi_spec`** - 获取并总结数据服务的 OpenAPI/Swagger 规范。返回可用端点及其参数的简明概述。
参数：`dataservice_id`（必需）
注意：推荐的工作流程：1) 使用 `search_dataservices` 查找 API，2) 使用 `get_dataservice_info` 获取其元数据和文档 URL，3) 使用 `get_dataservice_openapi_spec` 了解可用的端点和参数，4) 根据规范使用 `base_api_url` 调用 API。
### 指标
- **`get_metrics`** - 获取数据集和/或资源的指标（访问量、下载量）。
参数：`dataset_id`（可选），`resource_id`（可选），`limit`（可选，默认：12，最大：100）
返回月度统计数据，包括访问量和下载量，按月份降序排列（最近的在前）。必须至少提供 `dataset_id` 或 `resource_id` 之一。**注意：**此工具仅适用于生产环境（`DATAGOUV_API_ENV=prod`）。Metrics API 没有演示/预发布环境。
## 🧪 测试
### ✅ 使用 pytest 进行自动化测试
使用 pytest 运行测试（这些测试覆盖辅助模块；MCP Server 连接最好通过 MCP Inspector 进行测试）：
```
# 运行所有测试
uv run pytest
# 运行并输出详细信息
uv run pytest -v
# 运行特定测试文件
uv run pytest tests/test_tabular_api.py
# 运行并使用自定义 resource ID
RESOURCE_ID=3b6b2281-b9d9-4959-ae9d-c2c166dff118 uv run pytest tests/test_tabular_api.py
# 在 prod 环境下运行
DATAGOUV_API_ENV=prod uv run pytest
```
### 🔍 使用 MCP Inspector 进行交互式测试
使用官方 [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) 交互式测试服务器工具和资源。
前置条件：
- 安装了 Node.js 并提供 `npx`
步骤：
1. 启动 MCP Server（见上文）
2. 在另一个终端中，启动 inspector：
npx @modelcontextprotocol/inspector --http-url "http://127.0.0.1:${MCP_PORT}/mcp"
如果您将服务器暴露在另一个主机/端口上，请调整 URL。
## 🤝 贡献
我们欢迎贡献！为了保持项目稳定和审查易于管理，请在提交前遵守以下规则：
- **保持小型：**我们严格遵循 **1 个功能 = 1 个 PR** 的工作流程。
- **需要人工审查：**不要提交原始的 AI 生成代码。所有代码在提交前必须经过人工审查和测试。
我们使用标准的审查和部署流程：
1. **提交 PR：**通过针对 `main` 分支的 Pull Request 提出您的更改。
2. **审查：**所有 PR 在合并前必须由维护者审查和批准。
3. **自动部署：**一旦合并到 `main`，更改将部署到：
1. **[预发布环境](https://mcp.preprod.data.gouv.fr/)** 用于最终验证
2. **[生产环境](https://mcp.data.gouv.fr/)**
### 🧹 代码 Lint 和格式化
此项目遵循 PEP 8 风格指南，使用 [Ruff](https://astral.sh/ruff/) 进行 lint 和格式化，使用 [ty](https://docs.astral.sh/ty/) 进行类型检查。
**在提交贡献之前，必须手动运行这些命令或 [安装 pre-commit hook](#-pre-commit-hooks)。**
```
# Lint（包括 import 排序）并格式化代码
uv run ruff check --fix && uv run ruff format
# 类型检查 (ty)
uv run ty check
```
### 🔗 Pre-commit Hooks
此仓库使用 [pre-commit](https://pre-commit.com/) hook，它在每次提交前对代码进行 lint 和格式化。强烈建议安装 pre-commit hook，以便检查自动运行。
**安装 pre-commit hooks：**
```
uv run pre-commit install
```
自动执行以下操作的 pre-commit hook：
- 检查 YAML 语法
- 修复文件末尾问题
- 删除尾随空格
- 检查大文件
- 运行 Ruff lint 和格式化
### 🏷️ 发布和版本控制
发布过程使用 [`tag_version.sh`](tag_version.sh) 脚本创建 git tags、GitHub releases 并自动更新 [CHANGELOG.md](CHANGELOG.md)。包版本号使用 [setuptools_scm](https://github.com/pypa/setuptools_scm) 自动从 git tags 派生，因此 `pyproject.toml` 中不需要手动更新版本。
**前置条件**：必须安装并验证 [GitHub CLI](https://cli.github.com/)，并且您必须在 main 分支上且工作目录干净。
```
# 创建新版本
./tag_version.sh
# 示例
./tag_version.sh 2.5.0
# 空运行以查看将发生的操作
./tag_version.sh 2.5.0 --dry-run
```
该脚本自动：
- 提取自上次 tag 以来的提交并为 CHANGELOG.md 格式化它们
- 识别破坏性更改（主题中带有 `!:` 的提交）
- 创建 git tag 并将其推送到远程仓库
- 使用 changelog 内容创建 GitHub release
## 📄 许可证
此项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
[](https://circleci.com/gh/datagouv/datagouv-mcp)
[](https://opensource.org/licenses/MIT)
Model Context Protocol (MCP) server，允许 AI 聊天机器人（Claude、ChatGPT、Gemini 等）直接通过对话搜索、探索和分析来自 [data.gouv.fr](https://www.data.gouv.fr)（法国国家开放数据平台）的数据集。
无需手动浏览网站，您只需提问，例如“Quels jeux de données sont disponibles sur les prix de l'immobilier ?”或“Montre-moi les dernières données de population pour Paris”，即可获得即时答案。
## 🌐 将聊天机器人连接到 MCP Server
使用托管端点 `https://mcp.data.gouv.fr/mcp`（推荐）。如果您是自托管，请替换为您自己的 URL。
MCP Server 配置取决于您的客户端。请为您的客户端使用适当的配置格式：
[AnythingLLM](#anythingllm) | [ChatGPT](#chatgpt) | [Claude Code](#claude-code) | [Claude Desktop](#claude-desktop) | [Cursor](#cursor) | [Gemini CLI](#gemini-cli) | [HuggingChat](#huggingchat) | [IBM Bob](#ibm-bob) | [Kiro CLI](#kiro-cli) | [Kiro IDE](#kiro-ide) | [Le Chat (Mistral)](#le-chat-mistral) | [Mistral Vibe](#mistral-vibe-cli) | [VS Code](#vs-code) | [Windsurf](#windsurf)
### AnythingLLM
1. 在您的 AnythingLLM 存储 plugins 目录中找到 `anythingllm_mcp_servers.json` 文件：
- **Linux**: `~/.config/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json`
- **MacOS**: `~/Library/Application Support/anythingllm-desktop/storage/plugins/anythingllm_mcp_servers.json`
- **Windows**: `C:\Users\标签：AI聊天机器人, ChatGPT, Claude, CVE检测, DNS解析, Gemini, MCP服务器, Model Context Protocol, Promptflow, RAG, 代码示例, 公共数据平台, 大语言模型集成, 开放数据, 开源项目, 政府透明度, 数据分析, 数据连接器, 数据集检索, 智能助手, 法国政府数据, 自然语言查询, 请求拦截, 逆向工具