Insee Entreprises

Python 3.12+ MCP Claude Code License: MIT API SIRENE

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é
• 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 :

sudo apt-get install jq

Pour installer yq (version Go, recommandée) :

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) :

pip install yq

Installer UV

Pour installer uv, exécutez la commande suivante :

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 :

uv --version

Pour connaitre le chemin d'installation de uv, exécutez :

which uv

Pour ajouter uv à votre variable d'environnement PATH, ajoutez la ligne suivante à votre fichier de configuration de shell (~/.bashrc, ~/.zshrc, etc.) :

export PATH="$HOME/.local/bin:$PATH"

Après avoir modifié ce fichier, rechargez la configuration du shell avec :

source ~/.bashrc

Installation du serveur MCP

1. Cloner le dépôt (si ce n'est pas déjà fait) :

git clone [email protected]:DavidScanu/mcp-insee-entreprises.git
cd mcp-insee-entreprises

2. Installer les dépendances avec uv :

uv sync

3. Configurer la clé API INSEE :

Créez un fichier .env à la racine du projet:

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) :

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) :

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 :

which uv

5. Vérifier l'installation :

claude mcp list

Installation manuelle (alternative)

Si vous préférez configurer manuellement, ajoutez ceci à votre fichier ~/.claude.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 :

{
  "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 :

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 :

{
  "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 :

{
  "permissions": {
    "allow": [
      "mcp__insee-entreprises__search_by_siren",
      "mcp__insee-entreprises__search_by_siret"
    ]
  }
}

Gestion du serveur

# 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)
• 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 :

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 :

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 :

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) :

# 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&section_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.

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/