Content
# INSEE Entreprises MCP Server
[](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)
Serveur MCP (Model Context Protocol) pour interroger l'**API SIRENE** de l'INSEE et rechercher des entreprises françaises.
## Fonctionnalités
### 🔍 Outils disponibles
1. **search_by_siren** - Recherche par numéro SIREN (9 chiffres)
- Utilise l'API officielle INSEE Sirene
- Retourne les informations complètes et officielles de l'unité légale
- Données: dénomination, catégorie juridique, activité (NAF), effectifs, état administratif
2. **search_by_siret** - Recherche par numéro SIRET (14 chiffres)
- Utilise l'API officielle INSEE Sirene
- Retourne les informations complètes et officielles de l'établissement
- Données: adresse complète, activité (NAF), type d'établissement (siège/secondaire), effectifs, état administratif
3. **search_entreprises** - Recherche avancée avec filtres multiples
- Nom d'entreprise, adresse, dirigeant
- Filtres géographiques: code postal, commune, département, région
- Code NAF/APE
- Section d'activité (A-U) avec conversion automatique nom → code
- Nombre d'employés (min/max)
- Pagination disponible
## Prérequis
- Python 3.12+
- uv (gestionnaire de paquets Python)
- Clé API INSEE (gratuite) - [Obtenir une clé](https://portail-api.insee.fr/)
- jq (pour le formatage JSON dans les scripts bash)
- yq (pour convertir le schéma OpenAPI YAML en JSON)
#### Installer jq et yq
Pour installer jq :
```bash
sudo apt-get install jq
```
Pour installer yq (version Go, recommandée) :
```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
```
Ou via pip (version Python) :
```bash
pip install yq
```
### Installer UV
Pour installer `uv`, exécutez la commande suivante :
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Pour plus d'informations, consultez la documentation officielle : https://astral.sh/uv/docs/getting-started/installation
Pour vérifier l'installation, exécutez :
```bash
uv --version
```
Pour connaitre le chemin d'installation de `uv`, exécutez :
```bash
which uv
```
Pour ajouter `uv` à votre variable d'environnement PATH, ajoutez la ligne suivante à votre fichier de configuration de shell (`~/.bashrc`, `~/.zshrc`, etc.) :
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Après avoir modifié ce fichier, rechargez la configuration du shell avec :
```bash
source ~/.bashrc
```
## Installation du serveur MCP
1. **Cloner le dépôt** (si ce n'est pas déjà fait) :
```bash
git clone git@github.com:DavidScanu/mcp-insee-entreprises.git
cd mcp-insee-entreprises
```
2. **Installer les dépendances avec uv** :
```bash
uv sync
```
3. **Configurer la clé API INSEE** :
Créez un fichier `.env` à la racine du projet:
```bash
cp .env.example .env
```
Éditez le fichier `.env` et ajoutez votre clé API INSEE:
```
INSEE_API_KEY=votre_clé_api_ici
```
> **Note** : Pour obtenir gratuitement une clé API INSEE, rendez-vous sur https://portail-api.insee.fr/
4. **Ajouter le serveur MCP à Claude Code** (scope user) :
```bash
claude mcp add --transport stdio insee-entreprises --scope user -- uv --directory <chemin/absolu/vers/mcp-insee-entreprises> run insee-entreprises
```
> **Note** : Remplacez `<chemin/absolu/vers/mcp-insee-entreprises>` par le chemin absolu vers votre installation du serveur.
**Alternative si `uv` n'est pas dans votre PATH** :
Si la commande `uv` n'est pas reconnue, utilisez le chemin complet vers `uv` (généralement `~/.local/bin/uv` ou `~/.cargo/bin/uv`) :
```bash
claude mcp add --transport stdio insee-entreprises --scope user -- ~/.local/bin/uv --directory <chemin/absolu/vers/mcp-insee-entreprises> run insee-entreprises
```
Pour trouver le chemin complet vers `uv`, utilisez :
```bash
which uv
```
5. **Vérifier l'installation** :
```bash
claude mcp list
```
### Installation manuelle (alternative)
Si vous préférez configurer manuellement, ajoutez ceci à votre fichier `~/.claude.json` :
```json
{
"mcpServers": {
"insee-entreprises": {
"command": "uv",
"args": [
"--directory",
"/home/david/mcp-servers/mcp-insee-entreprises",
"run",
"insee-entreprises"
]
}
}
}
```
**Si `uv` n'est pas dans votre PATH**, utilisez le chemin absolu vers `uv` :
```json
{
"mcpServers": {
"insee-entreprises": {
"command": "/home/david/.local/bin/uv",
"args": [
"--directory",
"/home/david/mcp-servers/mcp-insee-entreprises",
"run",
"insee-entreprises"
]
}
}
}
```
> **Note** : Utilisez `which uv` pour trouver le chemin exact vers `uv` sur votre système.
> **Note** : Pour Claude Desktop, utilisez plutôt le fichier de configuration Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` sur macOS ou `%APPDATA%\Claude\claude_desktop_config.json` sur Windows).
## Configuration
### Scope d'installation
Ce serveur est installé en **scope user**, ce qui signifie qu'il est :
- Disponible pour tous vos projets Claude Code
- Stocké dans `~/.claude.json`
- Privé à votre compte utilisateur
### Autoriser automatiquement les appels de fonctions (User scope)
Pour éviter de cliquer sur "Oui" à chaque recherche avec le serveur MCP, vous pouvez autoriser automatiquement tous les outils du serveur INSEE en ajoutant des permissions au niveau **user** (tous vos projets).
#### Étape 1 : Vérifier que le serveur MCP est configuré
Assurez-vous que le serveur `insee-entreprises` est bien défini dans `~/.claude.json` :
```bash
claude mcp list
```
Vous devriez voir `insee-entreprises` dans la liste.
#### Étape 2 : Créer ou modifier le fichier de paramètres globaux
Créez ou modifiez le fichier `~/.claude/settings.json` :
```json
{
"enableAllProjectMcpServers": true,
"permissions": {
"allow": [
"mcp__insee-entreprises__*"
]
}
}
```
**Explication des paramètres :**
- `"enableAllProjectMcpServers": true` : Active automatiquement tous les serveurs MCP définis dans les fichiers `.mcp.json` de vos projets
- `"permissions.allow"` : Liste les outils autorisés automatiquement
- `"mcp__insee-entreprises__*"` : Autorise tous les outils du serveur MCP `insee-entreprises` (le `*` est un wildcard)
#### Étape 3 : Redémarrer Claude Code
Fermez et relancez Claude Code pour que les changements prennent effet.
#### Vérification
Une fois configuré, vous pouvez utiliser les outils MCP sans aucune demande d'autorisation :
```
Recherche les entreprises nommées "Carrefour"
```
Claude utilisera directement le serveur MCP sans demander de confirmation.
#### Alternative : Autoriser des outils spécifiques uniquement
Si vous préférez autoriser uniquement certains outils (par exemple, seulement la recherche par SIREN), remplacez le wildcard `*` par les noms des outils :
```json
{
"permissions": {
"allow": [
"mcp__insee-entreprises__search_by_siren",
"mcp__insee-entreprises__search_by_siret"
]
}
}
```
### Gestion du serveur
```bash
# Lister tous les serveurs MCP configurés
claude mcp list
# Obtenir les détails du serveur
claude mcp get insee-entreprises
# Supprimer le serveur
claude mcp remove insee-entreprises
# Vérifier le statut (dans Claude Code)
/mcp
```
## Utilisation
Une fois le serveur configuré, vous pouvez l'utiliser dans Claude Desktop :
### Exemples de requêtes
1. **Recherche par SIREN**
```
Trouve-moi les informations sur l'entreprise avec le SIREN 552032534
```
2. **Recherche par nom**
```
Recherche les entreprises nommées "Carrefour"
```
3. **Recherche par dirigeant**
```
Trouve les entreprises dirigées par "Jean Dupont"
```
4. **Recherche par activité**
```
Liste les entreprises avec le code NAF 62.01Z (programmation informatique)
```
5. **Recherche avancée**
```
Trouve les entreprises de programmation informatique à Paris avec plus de 50 employés
```
6. **Recherche par section d'activité**
```
Liste les entreprises dans la section "Construction" à Marseille
```
ou
```
Recherche les entreprises dans le secteur de l'information et communication (section J)
```
## Sections d'activité NAF
Le serveur supporte la recherche par section d'activité (niveau 1 de la nomenclature NAF). Vous pouvez utiliser soit le code (lettre A-U) soit le libellé de la section.
| Code | Libellé |
|------|---------|
| A | Agriculture, sylviculture et pêche |
| B | Industries extractives |
| C | Industrie manufacturière |
| D | Production et distribution d'électricité, de gaz, de vapeur et d'air conditionné |
| E | Production et distribution d'eau ; assainissement, gestion des déchets et dépollution |
| F | Construction |
| G | Commerce ; réparation d'automobiles et de motocycles |
| H | Transports et entreposage |
| I | Hébergement et restauration |
| J | Information et communication |
| K | Activités financières et d'assurance |
| L | Activités immobilières |
| M | Activités spécialisées, scientifiques et techniques |
| N | Activités de services administratifs et de soutien |
| O | Administration publique |
| P | Enseignement |
| Q | Santé humaine et action sociale |
| R | Arts, spectacles et activités récréatives |
| S | Autres activités de services |
| T | Activités des ménages en tant qu'employeurs |
| U | Activités extra-territoriales |
## Filtrage géographique
Le serveur supporte plusieurs niveaux de filtrage géographique :
### Codes postaux
```
Recherche les entreprises dans le code postal 75001
```
### Communes (Code INSEE)
```
Trouve les entreprises à Lyon (code commune 69123)
```
### Départements
```
Liste les entreprises en Isère (département 38)
```
### Régions
```
Recherche les entreprises en Auvergne-Rhône-Alpes (région 84)
```
### Filtres combinés
```
Trouve les entreprises de construction dans le département 38 avec plus de 100 employés
```
### Codes géographiques INSEE
Les codes géographiques suivent la nomenclature officielle de l'INSEE (COG 2025) :
| Type | Format | Exemple | Description |
|------|--------|---------|-------------|
| Code postal | 5 chiffres | 75001 | Code postal standard |
| Code commune | 5 caractères | 69123 | Code INSEE de la commune |
| Département | 2-3 chiffres | 38, 974 | Numéro de département (2 chiffres métropole, 3 chiffres outre-mer) |
| Région | 2 chiffres | 84 | Code région |
**Note :** Tous les paramètres géographiques acceptent des listes de valeurs séparées par des virgules pour effectuer des recherches sur plusieurs zones (ex: `departement=38,69` pour Isère et Rhône).
### Recherche par nom géographique
Le serveur MCP intègre un service de mapping qui permet de rechercher par nom géographique au lieu de codes :
**Régions :**
```
Recherche les entreprises en Auvergne-Rhône-Alpes
```
Le serveur convertira automatiquement "Auvergne-Rhône-Alpes" en code région "84".
**Départements :**
```
Trouve les entreprises dans le département de l'Isère
```
Le serveur convertira automatiquement "Isère" en code département "38".
**Communes :**
```
Liste les entreprises à Grenoble
```
Le serveur convertira automatiquement "Grenoble" en code commune "38185".
**Note importante pour les communes :** Plusieurs communes peuvent avoir le même nom. Dans ce cas, spécifiez également le département pour désambiguïser :
```
Trouve les entreprises à Saint-Martin dans le département 38
```
**Sources des codes géographiques :**
- [COG 2025 (Code Officiel Géographique)](https://www.insee.fr/fr/information/8377162)
- Données intégrées : régions, départements, communes (mise à jour janvier 2025)
## Informations retournées
Pour chaque entreprise, le serveur retourne :
- **Identification** : SIREN, dénomination sociale
- **Activité** : Code NAF/APE et libellé en français
- **Siège social** :
- Adresse complète (numéro, type de voie, nom de voie, code postal, commune)
- SIRET du siège
- **Établissements correspondants** :
- Jusqu'à 10 établissements avec leurs adresses complètes
- SIRET de chaque établissement
- Indication "(siège)" pour le siège social
- Nombre total d'établissements trouvés
- **Statut** : Actif/Inactif (en français)
- **Effectifs** : Tranche d'effectif salarié
- **Dirigeants** : Liste des dirigeants et leur fonction
### Format d'affichage optimisé
Les résultats de recherche avancée (`search_entreprises`) affichent maintenant :
- Le **siège social** avec son adresse complète et son SIRET
- Les **établissements correspondants** avec leurs adresses complètes et SIRET
- Une distinction claire entre le siège et les autres établissements
- Terminologie en français pour une meilleure lisibilité
## API Utilisées
Ce serveur MCP utilise deux API complémentaires de l'INSEE:
### 1. API INSEE Sirene (Officielle)
Utilisée pour les recherches **SIREN** et **SIRET** - Données officielles et complètes:
- **Base URL**: `https://api.insee.fr/api-sirene/3.11`
- **Authentification**: Clé API requise (gratuite) - configurée via le fichier `.env`
- **Endpoints**:
- `/siren/{siren}` - Informations sur l'unité légale
- `/siret/{siret}` - Informations sur l'établissement
- **Limite**: 30 requêtes/minute (en environnement d'intégration)
#### Documentation
- Portail API: https://portail-api.insee.fr/ (pour obtenir une clé API)
- Documentation complète: https://portail-api.insee.fr/catalog/api/2ba0e549-5587-3ef1-9082-99cd865de66f/doc
- Spécifications OpenAPI: https://api-apimanager.insee.fr/portal/environments/DEFAULT/apis/2ba0e549-5587-3ef1-9082-99cd865de66f/pages/6548510e-c3e1-3099-be96-6edf02870699/content
#### Exemple de requête curl
Recherche par 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"
```
Avec récupération automatique de la clé depuis le fichier `.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"
```
Avec formatage JSON via `jq` :
```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 '.'
```
#### Exemples de requêtes avec filtres géographiques
Recherche d'entreprises avec filtres géographiques (API Recherche Entreprises) :
```bash
# Recherche par code postal
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?code_postal=38000&per_page=5"
# Recherche par département
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?departement=38&per_page=5"
# Recherche par région
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?region=84&per_page=5"
# Recherche combinée: département + section d'activité
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?departement=38§ion_activite_principale=F&per_page=10"
# Recherche avec plusieurs départements
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?departement=38,69&per_page=10"
# Recherche avec code commune
curl -X GET "https://recherche-entreprises.api.gouv.fr/search?code_commune=38185&per_page=5"
```
### 2. API Recherche d'Entreprises
Utilisée pour la recherche **avancée** avec filtres multiples:
- **Base URL**: `https://recherche-entreprises.api.gouv.fr`
- **Authentification**: Aucune (accès libre)
- **Limite**: 7 requêtes par seconde
- **Disponibilité**: 100%
#### Documentation
- Documentation: 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
#### Limites
- Pas d'accès aux prédécesseurs/successeurs d'établissements
- Pas d'accès aux entreprises non diffusibles
- Pas d'accès aux rejets d'inscriptions RCS
### Test des APIs
Un script bash `scripts/insee_api.sh` est inclus pour tester les appels aux deux APIs. Assurez-vous d'avoir `jq` et `yq` installés pour le formatage JSON et la conversion du YAML vers JSON.
```bash
chmod +x scripts/insee_api.sh
./scripts/insee_api.sh
```
**Dépannage** :
- **Clé API INSEE invalide ou absente** : vérifiez le contenu du fichier `.env` et la variable `INSEE_API_KEY`.
- **Caractères spéciaux mal affichés (é, à , etc.)** : assurez-vous que votre terminal et vos fichiers sont en UTF-8.
- **Erreur : yq n'est pas installé** : installez `yq`.
- **Erreur : jq n'est pas installé** : installez `jq`.
---
## TODO
- ✅ Ajouter la recherche par critères géographiques (région, département, commune, code postal)
- ✅ Renommer `advanced_search` en `search_entreprises`
- ✅ Service de mapping géographique (nom → code) pour régions, départements et communes
- ✅ Tester le serveur MCP la recherche par SIREN et SIRET (API officielle INSEE Sirene 3.11)
- Tester le serveur MCP avec la nouvelle version de l'API INSEE Sirene (v4.0)
- Ajouter des exemples d'utilisation avancée dans la documentation
- Mettre à jour annuellement les données COG (Code Officiel Géographique)
---
## Développeur
Serveur MCP développé par **David Scanu**
- https://github.com/DavidScanu
- https://www.linkedin.com/in/davidscanu14/
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available