内容
INSEE 企业 MCP 服务器
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://claude.com/claude-code)
[](https://opensource.org/licenses/MIT)
[](https://www.data.gouv.fr/dataservices/api-recherche-dentreprises)
INSEE 企业 MCP 服务器，用于查询 **API SIRENE** 并搜索法国企业。
## 功能
### 🔍 可用工具
1. **search_by_siren** - 按 SIREN 号码（9 位数字）搜索
- INSEE Sirene API
- 返回合法单位的完整官方信息
- 数据：名称、法律类别、活动（NAF）、员工人数、行政状态
2. **search_by_siret** - 按 SIRET 号码（14 位数字）搜索
- 使用官方 INSEE Sirene API
- 返回机构的完整官方信息
- 数据：完整地址、活动（NAF）、机构类型（总部/分支）、员工人数、行政状态
3. **search_entreprises** - 高级搜索，支持多重过滤
- 企业名称、地址、负责人
- 地理过滤：邮政编码、市镇、部门、地区
- NAF/APE 代码
- 活动类别（A-U），自动转换名称为代码
- 员工人数（最小/最大）
- 支持分页
## 前置条件
- Python 3.12+
- uv（Python 包管理器）
- INSEE API 密钥（免费）- [获取密钥](https://portail-api.insee.fr/)
- jq（用于 bash 脚本中的 JSON 格式化）
- yq（用于将 OpenAPI YAML 转换为 JSON）
#### 安装 jq 和 yq
安装 jq：
```bash
sudo apt-get install jq
```
安装 yq（Go 版本，推荐）：
```bash
sudo wget -O /usr/local/bin/yq "https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64"
sudo chmod +x /usr/local/bin/yq
```
或通过 pip（Python 版本）：
```bash
pip install yq
```
### 安装 UV
安装 `uv`，执行以下命令：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
更多信息，请参阅官方文档：https://astral.sh/uv/docs/getting-started/installation
验证安装，执行：
```bash
uv --version
```
查找 `uv` 的安装路径，执行：
```bash
which uv
```
将 `uv` 添加到环境变量 PATH， 在 shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）中添加以下行：
```bash
export PATH="$HOME/.local/bin:$PATH"
```
修改文件后，重新加载 shell 配置：
```bash
source ~/.bashrc
```
## 安装 MCP 服务器
1. **克隆仓库**（如果尚未克隆）：
```bash
git clone git@github.com:DavidScanu/mcp-insee-entreprises.git
cd mcp-insee-entreprises
```
2. **使用 uv 安装依赖**：
```bash
uv sync
```
3. **配置 INSEE API 密钥** :
在项目根目录创建 `.env` 文件：
```bash
cp .env.example .env
```
编辑 `.env` 文件并添加您的 INSEE API 密钥：
```
INSEE_API_KEY=您的_API_密钥_此处
```
> **注意**：要免费获取 INSEE API 密钥，请访问 https://portail-api.insee.fr/
4. **将 MCP 服务器添加到 Claude Code** （用户范围）:
```bash
claude mcp add --transport stdio insee-entreprises --scope user -- uv --directory <mcp-insee-entreprises 绝对路径> run insee-entreprises
```
> **注意**：将 `<mcp-insee-entreprises 绝对路径>` 替换为您的实际安装路径。
**如果 `uv` 不在您的 PATH 中**：
如果 `uv` 命令无法识别，请使用 `uv` 的完整路径（通常为 `~/.local/bin/uv` 或 `~/.cargo/bin/uv`）：
```bash
claude mcp add --transport stdio insee-entreprises --scope user -- ~/.local/bin/uv --directory <mcp-insee-entreprises 绝对路径> run insee-entreprises
```
查找 `uv` 的完整路径：
```bash
which uv
```
5. **验证安装**：
```bash
claude mcp list
```
### 手动安装（替代方案）
如果您更喜欢手动配置，请在 `~/.claude.json` 文件中添加以下内容：
```json
{
"mcpServers": {
"insee-entreprises": {
"command": "uv",
"args": [
"--directory",
"/home/david/mcp-servers/mcp-insee-entreprises",
"run",
"insee-entreprises"
]
}
}
}
```
**如果 `uv` 不在您的 PATH 中**，请使用 `uv` 的绝对路径：
```json
{
"mcpServers": {
"insee-entreprises": {
"command": "/home/david/.local/bin/uv",
"args": [
"--directory",
"/home/david/mcp-servers/mcp-insee-entreprises",
"run",
"insee-entreprises"
]
}
}
}
```
> **注意**：使用 `which uv` 查找 `uv` 的确切路径。
> **注意**：对于 Claude Desktop，请使用配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS 或 `%APPDATA%\Claude\claude_desktop_config.json` on Windows）。
## 配置
### 安装范围
该服务器安装在 **用户范围**，这意味着它：
- 对您所有的 Claude Code 项目可用
- 存储在 `~/.claude.json`
- 对您的用户账户私有
### 自动授权函数调用（用户范围）
为了避免每次使用 MCP 服务器进行搜索时都需要点击“是”，您可以通过在 **用户级别**（所有项目）添加权限来自动授权 INSEE 服务器的所有工具。
#### 步骤 1：验证 MCP 服务器已配置
确保 `insee-entreprises` 服务器已在 `~/.claude.json` 中定义：
```bash
claude mcp list
```
您应该在列表中看到 `insee-entreprises`。
#### 步骤 2：创建或修改全局设置文件
创建或修改 `~/.claude/settings.json` 文件：
```json
{
"enableAllProjectMcpServers": true,
"permissions": {
"allow": [
"mcp__insee-entreprises__*"
]
}
}
```
**参数解释：**
- `"enableAllProjectMcpServers": true`：自动启用所有项目中定义的 MCP 服务器
- `"permissions.allow"`：列出自动授权的工具
- `"mcp__insee-entreprises__*"`：授权 `insee-entreprises` 服务器的所有工具（`*` 为通配符）
#### 步骤 3：重启 Claude Code
关闭并重新启动 Claude Code 以使更改生效。
#### 验证
配置完成后，您可以在不进行任何授权请求的情况下使用 MCP 工具：
```
查找名称为“Carrefour”的企业
```
Claude 将直接使用 MCP 服务器而无需确认。
#### 替代：仅授权特定工具
如果您更喜欢仅授权某些工具（例如，仅 SIREN 搜索），请将通配符 `*` 替换为工具名称：
```json
{
"permissions": {
"allow": [
"mcp__insee-entreprises__search_by_siren",
"mcp__insee-entreprises__search_by_siret"
]
}
}
```
### 服务器管理
```bash
# 列出所有已配置的 MCP 服务器
claude mcp list
# 获取服务器详细信息
claude mcp get insee-entreprises
# 删除服务器
claude mcp remove insee-entreprises
# 检查状态（在 Claude Code 中)
/mcp
```
## 使用
配置服务器后，您可以在 Claude Desktop 中使用它：
### 查询示例
1. **按 SIREN 搜索**
```
查找 SIREN 为 552032534 的企业信息
```
2. **按名称搜索**
```
查找名称为“Carrefour”的企业
```
3. **按负责人搜索**
```
查找由“Jean Dupont”负责的企业
```
4. **按活动搜索**
```
列出 NAF 代码为 62.01Z（计算机编程）的企业
```
5. **高级搜索**
```
查找巴黎的计算机编程企业，员工超过 50 人
```
6. **按活动类别搜索**
```
列出马赛的“建筑”行业的企业
```
或
```
搜索信息和通信行业（J 类别）的企业
```
## NAF 活动类别
服务器支持按活动类别（NAF 分类第一级）搜索。您可以使用代码（字母 A-U）或类别名称。
| 代码 | 类别名称 |
|------|---------|
| A | 农业、林业和渔业 |
| B | 采矿业 |
| C | 制造业 |
| D | 电力、天然气、蒸汽和空调供应 |
| E | 水供应、污水处理、废物管理和污染治理 |
| F | 建筑业 |
| G | 商业；机动车和摩托车维修 |
| H | 运输和仓储 |
| I | 住宿和餐饮服务 |
| J | 信息和通信 |
| K | 金融和保险活动 |
| L | 房地产活动 |
| M | 专业、科学和技术活动 |
| N | 行政和支持服务 |
| O | 公共管理 |
| P | 教育 |
| Q | 人类健康和社会工作 |
| R | 艺术、娱乐和休闲活动 |
| S | 其他服务 |
| T | 家庭作为雇主的活动 |
| U | 跨界活动 |
## 地理过滤
服务器支持多个级别的地理过滤：
### 邮政编码
```
查找 75001 邮政编码区域内的企业
```
### 市镇（INSEE 代码）
```
查找里昂市镇（市镇代码 69123）的企业
```
### 部门
```
列出伊泽尔部门（部门 38）的企业
```
### 地区
```
查找奥弗涅-罗讷-阿尔卑斯地区（地区 84）的企业
```
### 组合过滤
```
查找 38 部门的建筑业企业，员工超过 100 人
```
### INSEE 地理代码
地理代码遵循 INSEE 官方命名法（COG 2025）：
| 类型 | 格式 | 示例 | 描述 |
|------|--------|---------|-------------|
| 邮政编码 | 5 位数字 | 75001 | 标准邮政编码 |
| 市镇代码 | 5 个字符 | 69123 | 市镇的 INSEE 代码 |
| 部门 | 2-3 位数字 | 38, 974 | 部门编号（大都市为 2 位，海外为 3 位） |
| 地区 | 2 位数字 | 84 | 地区代码 |
**注意：** 所有地理参数都接受用逗号分隔的值列表，以在多个区域上执行搜索（例如，`departement=38,69` 表示伊泽尔和罗讷部门）。
### 按地理名称搜索
MCP 服务器集成了映射服务，允许按地理名称而不是代码搜索：
**地区：**
```
查找奥弗涅-罗讷-阿尔卑斯地区的企业
```
服务器将自动将“奥弗涅-罗讷-阿尔卑斯”转换为地区代码“84”。
**部门：**
```
查找伊泽尔部门的企业
```
服务器将自动将“尔”转换为部门代码“38”。
**市镇：**
```
列出格勒诺布尔的企业
```
服务器将自动将“格勒诺布尔”转换为市镇代码“38185”。
**重要注意：** 对于市镇，多个市镇可能具有相同的名称。在指定部门以消除歧义：
```
查找 38 部门的圣马丁市镇的企业
```
**地理代码来源：**
- [COG 2025地理代码）://www.insee/information/2)
- 集成数据：地区、镇（2025 年 1 月更新## 返回信息每个企业，服务器- **：SIREN- **活动NAF/APE 代码和法语名称
总部 - 完整地址（编号、街道类型、街道名称、邮政编码、市镇）
- 总部 SIRET
- **对应机构**：
- 最多 10 个机构及其完整地址
- 每个机构的 SIRET
- 标识（总部）表示总部
- 找到的机构总数
- **状态有效/无效（- ****：员工- **负责人**：负责人列表及其职务
### 优化显示格式
高级搜索结果_entreprises`）现在显示：
总部**及其完整地址和 SIRET
- **对应机构**及其完整地址和 SIRET
- 清楚地区分总部和其他机构
- 法语术语以提高可读性
## 使用的 API
MCP 服务器使用 INSEE 的两个补充 API：
###. INSEE Sir（官方）
用于 **SIREN** 和 **SIRET** 搜索 - 官方完整数据：
- **基准 URL**：`https://api.insee.fr/api-sirene/3.11`
- **身份验证**：需要 API 密钥（免费 通过 `.env` 文件配置
- **端点**：
- `/siren/{siren}` - 合法单位信息
- `/siret/{siret}` - 机构信息
- **限制**：每分钟 30 次请求（集成环境）
#### 文档
- API 门户：https://portail-api.insee.fr/ （获取 API 密钥）
- 完整文档：https://portail-api.insee.fr/catalog/api/2ba0e549-5587-3ef1-9082-99cd865de66f/doc
- OpenAPI 规范：https://api-apimanager.insee.fr/portal/environments/DEFAULT/apis/2ba0e549-5587-3ef1-9082-99cd865de66f/pages/6548510e-c3e1-3099-be96-6edf02870699/content
#### curl 请求示例
按 SIRET 搜索：
```bash
curl -X GET "https://api.insee.fr/api-sirene/3.11/siret/67205008502051" \
-H "X-INSEE-Api-Key-Integration: VOTRE_CLE_API_INSEE"
```
自动从 `.env` 文件中检索密钥：
```bash
source .env && curl -X GET "https://api.insee.fr/api-sirene/3.11/siret/67205008502051" \
-H "X-INSEE-Api-Key-Integration: $INSEE_API_KEY"
```
使用 `jq` 进行 JSON 格式化：
```bash
source .env && curl -X GET "https://api.insee.fr/api-sirene/3.11/siret/67205008502051" \
-H "X-INSEE-Api-Key-Integration: $INSEE_API_KEY" | jq '.'
```
#### 地理过滤搜索示例
具有多个过滤器的企业搜索（企业搜索 API）：
```bash
# 按邮政编码搜索
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?code_postal=38000&per_page=5"
# 按部门搜索
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?departement=38&per_page=5"
# 按地区搜索
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?region=84&per_page=5"
# 组合搜索：部门 + 活动类别
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?departement=38§ion_activite_principale=F&per_page=10"
# 搜索多个部门
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?departement=38,69&per_page=10"
# 按市镇代码搜索
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?code_commune=38185&per_page=5"
```
### 2. 企业搜索 API
用于具有多个过滤器的 **高级** 搜索：
基准 URL**：`https://-entreprises.api.gouv.fr`
- **身份验证**：无（开放访问）
- **限制**：每秒 7 次请求
- **可用性**：100%
#### 文档
- 文档：https://www.data.gouv.fr/dataservices/api-recherche-dentreprises
- Swagger：https://recherche-entreprises.api.gouv.fr/docs/
- OpenAPI：https://recherche-entreprises.api.gouv.fr/openapi.json
#### 限制
- 无法访问机构的前身/继承者信息
- 无法访问不可公开的企业信息
- 无法访问 RCS 注册拒绝信息
### 测试 API
`scripts/insee_api.sh` 脚本包含用于测试两个 API 调用的 bash 脚本。确保已安装 `jq`yq` 以进行 JSON 格式化和 YAML 到 JSON 转换。
```bash
chmod +x scripts_api.sh
./see_api.sh
```
****：
- **INSEE API 密钥无效或缺失**：请检查 `.env` 文件的内容和 `INSEE_API_KEY` 变量。
- **特殊字符显示不正确（Ãé, Ã , 等）**：和文件为 UTF-8 编码。
- **错误：yq 未安装**：安装 `yq`。
- **错误：jq 未安装**：安装 `jq`。
---
##事项
- ✅ 添加地理（地区、部门、市镇、邮政编码）
- ✅ 将 `advanced_search` 重命名为 `search_`
- ✅ 地理映射服务（名称到代码）用于地区、部门和市镇
- ✅ 使用 Sirene 官方 API 测试服务器的 SIREN 和 SIRET 搜索（版本 3.11）
- 测试具有新版 INSEE Sirene API（v4.0）的服务器
- 在文档中添加高级用法- 每年更新 COG 数据
---
## 开发者
MCP 服务器由 **David Scanu** 开发
- https://github.com/David
- https://www.linkedin.com/in/davidscanu14/
