🇫🇷 France Travail MCP

Serveur MCP (Model Context Protocol) pour les API officielles de France Travail : offres d'emploi, référentiel des métiers ROME 4.0, prédiction ROMEO, et entreprises qui recrutent (La Bonne Boîte).

An MCP server connecting any AI assistant (Claude, Cursor, VS Code…) to the official France Travail APIs: real-time job offers, the ROME occupational taxonomy, ROME-code prediction, and hiring-company search.

Branchez votre assistant IA sur le marché de l'emploi français : il cherche des offres en temps réel, traduit un métier en code ROME, et cible les entreprises qui recrutent — directement dans la conversation.

C'est, à notre connaissance, le premier serveur MCP basé sur les API REST officielles de France Travail (les autres « MCP France Travail » sont des scrapers du site web, fragiles et non officiels).

⚡ Installation en 30 secondes

Dans tous les cas, il vous faut des identifiants France Travail (gratuits) — voir Obtenir vos identifiants.

🖱️ Option A — La plus simple, sans terminal (Claude Desktop)

1. Téléchargez le fichier france-travail-mcp.mcpb depuis la page Releases.
2. Double-cliquez dessus : Claude Desktop l'installe et vous demande votre Client ID / Client Secret dans un formulaire (le secret est stocké dans le trousseau de votre système).
3. C'est prêt — aucune édition de fichier JSON.

⌨️ Option B — Une ligne (Claude Code)

claude mcp add france-travail \
  -e FT_CLIENT_ID=PAR_xxxxx \
  -e FT_CLIENT_SECRET=votre_secret \
  -- npx -y france-travail-mcp

🧩 Option C — Copier-coller (Claude Desktop, Cursor, VS Code…)

{
  "mcpServers": {
    "france-travail": {
      "command": "npx",
      "args": ["-y", "france-travail-mcp"],
      "env": {
        "FT_CLIENT_ID": "PAR_xxxxx_xxxxxxxxxxxxxxxxxxxx",
        "FT_CLIENT_SECRET": "votre_secret"
      }
    }
  }
}

📖 Guide complet par client (Cursor, VS Code/Cline, et Ollama 100 % local) → INSTALL.md.

🔑 Obtenir vos identifiants

1. Créez un compte sur francetravail.io.
2. Créez une application dans votre espace.
3. Souscrivez aux API souhaitées (au minimum Offres d'emploi v2 ; puis ROME 4.0 – Métiers, ROME 4.0 – Fiches métiers, ROMEO 2, La Bonne Boîte v2 selon les outils voulus).
4. Récupérez le Client ID (PAR_…) et le Client Secret.

Prérequis : Node.js ≥ 18 (sauf l'option A, qui est autoportée).

🧰 Outils exposés

| Outil | Description | API France Travail | Statut | |-------|-------------|--------------------|--------| | ft_search_offres | Recherche multicritères d'offres (mots-clés, ROME, géo, contrat, salaire…) | Offres d'emploi v2 | ✅ testé en live | | ft_get_offre | Détail complet d'une offre | Offres d'emploi v2 | ✅ testé en live | | ft_list_referentiel | Référentiels (communes, types de contrats…) codes ↔ libellés | Offres d'emploi v2 | ✅ testé en live | | ft_search_metiers | Trouver un métier ROME et son code par texte | ROME 4.0 – Métiers | ✅ testé en live | | ft_get_metier | Fiche d'un métier ROME (définition, accès) | ROME 4.0 – Métiers | ✅ testé en live | | ft_get_fiche_metier | Compétences & savoirs d'un métier | ROME 4.0 – Fiches métiers | ✅ testé en live | | ft_predict_rome | Deviner le code ROME d'un intitulé libre (IA) | ROMEO 2 | ✅ testé en live | | ft_search_entreprises | Entreprises à fort potentiel d'embauche | La Bonne Boîte v2 | ⚠️ désactivé par défaut |

La Bonne Boîte est une API à accès conditionné : la simple souscription ne suffit pas, France Travail exige une habilitation validée manuellement (sans elle, l'API renvoie 403 Invalid scope). L'outil ft_search_entreprises est donc désactivé par défaut ; une fois l'accès accordé, activez-le avec la variable d'environnement FT_ENABLE_LABONNEBOITE=true (son endpoint exact reste à confirmer).

Les autres outils s'activent automatiquement dès que l'API correspondante est souscrite, sans changement de code.

🧪 Exemple — l'agent enchaîne les outils tout seul

« Je suis pâtissier et je cherche un CDI vers Lyon. »

1. ft_predict_rome("pâtissier") → code ROME D1104
2. ft_search_offres(codeROME=["D1104"], commune="69381", typeContrat=["CDI"])
3. ft_search_entreprises(...) pour les candidatures spontanées.

⚠️ Paris, Lyon et Marseille s'indiquent par arrondissement (Lyon 1er = 69381, Paris 1er = 75101, Marseille 1er = 13201) : les codes « globaux » 69123 / 75056 / 13055 sont refusés par l'API (erreur 400). Récupérez les bons codes avec ft_list_referentiel.

🔐 Correspondance outils ↔ scopes OAuth

Chaque API a son propre scope. Le serveur demande un token par scope (mis en cache ~25 min). Pour activer un groupe d'outils, votre application doit avoir souscrit à l'API correspondante :

| API à souscrire | Scope OAuth | Active | |-----------------|-------------|--------| | Offres d'emploi v2 | api_offresdemploiv2 o2dsoffre | ft_search_offres, ft_get_offre, ft_list_referentiel | | ROME 4.0 – Métiers | api_rome-metiersv1 nomenclatureRome | ft_search_metiers, ft_get_metier | | ROME 4.0 – Fiches métiers | api_rome-fiches-metiersv1 nomenclatureRome | ft_get_fiche_metier | | ROMEO 2 | api_romeov2 | ft_predict_rome | | La Bonne Boîte v2 | api_labonneboitev2 | ft_search_entreprises |

🛠️ Développement

git clone https://github.com/jojolabagarre/france-travail-mcp.git
cd france-travail-mcp
npm install              # installe les dépendances ET compile (script "prepare")
cp .env.example .env     # renseignez FT_CLIENT_ID / FT_CLIENT_SECRET
npm run smoke            # test de bout en bout contre l'API réelle

| Commande | Rôle | |---|---| | npm run build | Compile TypeScript → dist/ | | npm test | Vérifie les types (tsc --noEmit) | | npm run smoke | Test de bout en bout contre l'API réelle | | npm start | Démarre le serveur (transport stdio) | | npm run bundle | Génère le bundle .mcpb (Claude Desktop) |

Stack : TypeScript · @modelcontextprotocol/sdk · zod · axios. Transport stdio. Architecture : src/services (auth OAuth2 + client HTTP + erreurs), src/schemas, src/tools (un fichier par domaine). Voir CONTRIBUTING.md.

📦 Publication (mainteneur)

La publication est automatique sur un tag de version (npm puis registre MCP officiel) :

npm version patch        # met à jour la version, crée le commit + le tag
git push --follow-tags   # déclenche le workflow de publication

Voir .github/workflows/publish-mcp.yml. Secret requis dans le dépôt : NPM_TOKEN (jeton npm). L'authentification au registre MCP se fait par OIDC (aucun secret supplémentaire).

🔒 Sécurité

• Le fichier .env n'est jamais committé (voir .gitignore).
• Les identifiants sont fournis au serveur via les variables d'environnement du client MCP (ou le formulaire sécurisé du bundle .mcpb).
• Ne partagez jamais votre client_secret. En cas de fuite, régénérez-le sur francetravail.io.

🗺️ Feuille de route

• [ ] La Bonne Alternance (offres + formations en alternance)
• [ ] Marché du travail (statistiques, tensions de recrutement par bassin)
• [ ] Validation/finalisation de ft_search_entreprises (La Bonne Boîte)
• [x] Publication npm + registre MCP + bundle .mcpb

🤝 Contribuer

Les contributions sont bienvenues : ouvrez une issue ou une pull request. Voir CONTRIBUTING.md.

📄 Licence & avertissement

Sous licence MIT (voir LICENSE).

Projet non officiel, non affilié à France Travail. Il consomme les API publiques de France Travail ; leur usage est soumis aux conditions d'utilisation de francetravail.io. « France Travail », « ROME » et « La Bonne Boîte » sont des marques de France Travail.