france-travail-mcp

🇫🇷 France Travail MCP

France Travail の公式 API（求人情報、職業分類 ROME 4.0、ROMEO による予測、採用企業検索 La Bonne Boîte）向けの MCP（Model Context Protocol）サーバーです。

あらゆる AI アシスタント（Claude、Cursor、VS Code…）を France Travail の公式 API に接続する MCP サーバーです。リアルタイムの求人情報、ROME 職業分類体系、ROME コードの予測、採用企業の検索に対応しています。

AI アシスタントをフランスの雇用市場につなぎましょう。会話の中で、リアルタイムの求人情報を検索し、職業を ROME コードに変換し、採用中の企業を特定できます。

私たちの知る限り、これは France Travail の公式 REST API を基盤とする初の MCP サーバーです（他の「France Travail MCP」はウェブサイトの スクレイパー であり、壊れやすく、非公式です）。

---

⚡ 30 秒でインストール

いずれの方法でも、France Travail の認証情報（無料）が必要です。詳しくは認証情報の取得をご覧ください。

🖱️ オプション A — 最も簡単、ターミナル不要（Claude Desktop）

1. Releases ページから france-travail-mcp.mcpb ファイルをダウンロードします。
2. ファイルをダブルクリックします。Claude Desktop がインストールし、Client ID / Client Secret の入力をフォームで求めます（シークレットはシステムのキーチェーンに保存されます）。
3. これで完了です。JSON ファイルの編集は不要です。

⌨️ オプション B — 1 行（Claude Code）

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

🧩 オプション C — コピー＆ペースト（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"
      }
    }
  }
}

📖 クライアント別の詳しいガイド（Cursor、VS Code/Cline、完全ローカルの Ollama）→ INSTALL.md。

---

🔑 認証情報の取得

1. francetravail.io でアカウントを作成します。
2. ご自身のページでアプリケーションを作成します。
3. 使用する API を登録します（最低限 Offres d'emploi v2。必要なツールに応じて、ROME 4.0 – Métiers、ROME 4.0 – Fiches métiers、ROMEO 2、La Bonne Boîte v2 も登録してください）。
4. Client ID（PAR_…）と Client Secret を取得します。

前提条件：Node.js ≥ 18（自動完結型のオプション A を除く）。

---

🧰 公開されるツール

ツール	説明	France Travail API	ステータス
ft_search_offres	求人の複数条件検索（キーワード、ROME、地域、契約、給与など）	Offres d'emploi v2	✅ 実環境でテスト済み
ft_get_offre	求人の詳細情報	Offres d'emploi v2	✅ 実環境でテスト済み
ft_list_referentiel	参照データ（市区町村、契約種別など）のコード ↔ 表記	Offres d'emploi v2	✅ 実環境でテスト済み
ft_search_metiers	テキストから職業とその ROME コードを検索	ROME 4.0 – Métiers	✅ 実環境でテスト済み
ft_get_metier	ROME 職業情報（定義、就業へのアクセス）	ROME 4.0 – Métiers	✅ 実環境でテスト済み
ft_get_fiche_metier	職業のスキルと知識	ROME 4.0 – Fiches métiers	✅ 実環境でテスト済み
ft_predict_rome	自由記述の職種名から ROME コードを予測（AI）	ROMEO 2	✅ 実環境でテスト済み
ft_search_entreprises	採用の可能性が高い企業	La Bonne Boîte v2	⚠️ デフォルトで無効

La Bonne Boîte は アクセスに条件がある API です。単に利用登録するだけでは不十分で、France Travail による手動の認可が必要です（認可がない場合、API は 403 Invalid scope を返します）。そのため、ツール ft_search_entreprises はデフォルトで無効です。アクセスが許可されたら、環境変数 FT_ENABLE_LABONNEBOITE=true で有効にしてください（正確なエンドポイントは確認が必要です）。

ほかのツールは、対応する API を利用登録すると、コードを変更せずに自動で有効になります。

---

🧪 例 — エージェントがツールを自動で連続実行します

「パティシエをしていて、リヨン周辺で無期雇用契約の仕事を探しています。」

1. ft_predict_rome("pâtissier") → ROME コード D1104
2. ft_search_offres(codeROME=["D1104"], commune="69381", typeContrat=["CDI"])
3. 自発的な応募のために ft_search_entreprises(...) を実行します。

⚠️ パリ、リヨン、マルセイユは区単位で指定します（リヨン第 1 区 = 69381、パリ第 1 区 = 75101、マルセイユ第 1 区 = 13201）。「全域」を示すコード 69123 / 75056 / 13055 は API に拒否されます（エラー 400）。ft_list_referentiel で正しいコードを取得してください。

---

🔐 ツールと OAuth スコープの対応

各 API には独自の スコープ があります。サーバーはスコープごとにトークンを 1 つ要求します（約 25 分間キャッシュ）。ツールのグループを有効にするには、アプリケーションで対応する API を利用登録する必要があります。

利用登録する API	OAuth スコープ	有効になるツール
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

---

🛠️ 開発

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

コマンド	役割
npm run build	TypeScript をコンパイル → dist/
npm test	型を検証（tsc --noEmit）
npm run smoke	実際の API に対するエンドツーエンドテスト
npm start	サーバーを起動（stdio トランスポート）
npm run bundle	.mcpb バンドルを生成（Claude Desktop）

スタック：TypeScript · @modelcontextprotocol/sdk · zod · axios。トランスポートは stdio です。 アーキテクチャ：src/services（OAuth2 認証 + HTTP クライアント + エラー）、src/schemas、src/tools（ドメインごとに 1 ファイル）。CONTRIBUTING.md を参照してください。

📦 公開（メンテナー向け）

バージョンタグを付けると、公開が自動的に行われます（npm の後に公式 MCP レジストリ）：

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

.github/workflows/publish-mcp.yml を参照してください。リポジトリに必要なシークレット：NPM_TOKEN（npm トークン）。MCP レジストリへの認証には OIDC を使用するため、追加のシークレットは不要です。

🔒 セキュリティ

• .env はコミットされません（.gitignore を参照）。
• 認証情報は、MCP クライアントの環境変数（または .mcpb バンドルの安全なフォーム）を通じてサーバーに渡されます。
• client_secret は決して共有しないでください。漏えいした場合は、francetravail.io で再生成してください。

🗺️ ロードマップ

• La Bonne Alternance（交互就業の求人＋研修）
• 労働市場（統計、地域別の採用難易度）
• ft_search_entreprises（La Bonne Boîte）の検証／最終調整
• npm での公開＋MCP レジストリ＋.mcpb バンドル

🤝 コントリビューション

コントリビューションを歓迎します。イシューまたはプルリクエストを作成してください。CONTRIBUTING.md を参照してください。

📄 ライセンスと免責事項

MIT ライセンスの下で提供されます（LICENSE を参照）。

非公式プロジェクトであり、France Travail とは提携していません。France Travail の公開 API を利用しており、その使用には francetravail.io の利用規約が適用されます。「France Travail」、「ROME」、「La Bonne Boîte」は France Travail の商標です。