france-travail-mcp

🇫🇷 France Travail MCP

面向 France Travail 官方 API 的 MCP（Model Context Protocol）服务：职位信息、ROME 4.0 职业分类、ROMEO 预测，以及正在招聘的企业（La Bonne Boîte）。

一款 MCP 服务，可将任意 AI 助手（Claude、Cursor、VS Code…）连接到 France Travail 官方 API：实时职位信息、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 — 一行命令（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，以及 100% 本地运行的 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 后，其他工具会自动启用，无需更改代码。

---

🧪 示例 — Agent 自动串联工具

「我是一名糕点师，正在里昂附近找一份 CDI。」

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）：API 不接受「全市」代码 69123 / 75056 / 13055（错误 400）。请使用 ft_list_referentiel 获取正确代码。

---

🔐 工具 ↔ OAuth scope 对应关系

每个 API 都有自己的 scope。服务会针对每个 scope 请求一个 token（缓存约 25 分钟）。若要启用一组工具，你的应用必须订阅相应的 API：

要订阅的 API	OAuth scope	启用的工具
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 bundle（Claude Desktop）

技术栈：TypeScript · @modelcontextprotocol/sdk · zod · axios。传输方式：stdio。 架构：src/services（OAuth2 身份验证 + HTTP 客户端 + 错误处理）、src/schemas、src/tools（每个领域对应一个文件）。请参阅 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 令牌）。通过 OIDC 向 MCP 注册表进行身份验证（无需其他密钥）。

🔒 安全

• .env 文件绝不会提交（参见 .gitignore）。
• 凭据通过 MCP 客户端的环境变量（或 .mcpb 捆绑包的安全表单）提供给服务。
• 切勿分享您的 client_secret。如果泄露，请在 francetravail.io 上重新生成。

🗺️ 路线图

• La Bonne Alternance（交替制工作机会 + 培训）
• 劳动力市场（统计数据、各就业区域的招聘压力）
• 验证/最终确定 ft_search_entreprises（La Bonne Boîte）
• 发布至 npm + MCP 注册表 + .mcpb 捆绑包

🤝 贡献

欢迎贡献：请提交 issue 或 pull request。参见 CONTRIBUTING.md。

📄 许可证与免责声明

采用 MIT 许可证（参见 LICENSE）。

本项目非官方，与 France Travail 无关联。本项目使用 France Travail 的公共 API；使用须遵守 francetravail.io 的使用条款。“France Travail”、“ROME”和“La Bonne Boîte”均为 France Travail 的商标。