freehire

freehire MCP 服务

一个基于 freehire 职位 API 的 MCP 服务。它让任意 MCP 宿主（Claude Desktop、Claude Code 或兼容的 Agent） 无需浏览器即可搜索、筛选 IT 职位并申请，并通过个人 API 密钥进行身份验证。职位信息直接从公司招聘页面抓取：覆盖 294K 家公司的 3.3M+ 个开放职位，统一为一种架构，并按技术栈、资历、地区和工作模式添加标签（实时数据）。

它与 freehire CLI 功能一致： 使用相同的 API 和凭据，只是以 MCP 工具而非 shell 命令的形式提供。

安装

托管端点（无需安装和密钥）

只读职位搜索工具也通过远程方式提供，地址为 https://freehire.me/api/v1/mcp（Streamable HTTP）。在 Claude Code 中，将其安装为插件：

/plugin install freehire --marketplace strelov1/freehire-mcp

在其他宿主中，将该 URL 添加为自定义远程连接器。

本地服务（npm）

无需全局安装，宿主会通过 npx 运行它。将其添加到宿主的 MCP 配置中（Claude Desktop → 设置 → 开发者 → 编辑配置，或 Claude Code 的 ~/.claude.json）：

{
  "mcpServers": {
    "freehire": {
      "command": "npx",
      "args": ["-y", "freehire-mcp"],
      "env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
    }
  }
}

在 Web 应用中创建 fhk_… 密钥（freehire.me → 账户菜单 → API 密钥）。 如果你已经在使用 freehire CLI（freehire auth login），可以省略 env—— 服务会读取同一个 ~/.freehire/creds.json。

身份验证

令牌和 API 基础 URL 按以下优先级解析： 环境变量 → ~/.freehire/creds.json → 默认值 https://freehire.me：

内容	来源
令牌	FREEHIRE_TOKEN → 凭据文件
API 基础 URL	FREEHIRE_API_URL → 凭据文件 → https://freehire.me

服务只读取凭据文件（不会写入；登录仍由 CLI 负责）。如果未配置令牌，工具会返回清晰的“未通过身份验证”错误，而不会导致服务启动失败。

工具

工具	用途
whoami	已认证的用户（验证密钥）。
profile	候选人保存的求职资料（技能、偏好、不含联系方式的简历）。
facets	筛选条件／技能词汇表：每个筛选项的实时取值及数量。请先调用。
search	关键词 + 筛选项职位搜索；返回职位，包含完整的 Markdown 格式描述，以及匹配总数。
market_fit	根据实时市场需求评估技能列表（覆盖情况 + 差距）。
job	根据 slug 获取单个职位的完整内容。
company	根据 slug 获取公司信息及其开放职位。
apply	标记已申请某职位。
save / unsave	收藏／取消收藏。
stage	设置申请阶段（由服务端验证）。
note	添加自由文本备注。
my	调用者跟踪的职位（全部／已查看／已收藏／已申请），包含阶段 + 备注。
cv_tailor	开始（或重新打开）针对某个职位定制简历；返回其他 cv_* 工具所需的简历 ID。
cv_list	调用者定制的简历，以及每份简历对应的职位。
cv_context	定制简历应侧重呈现的匹配分析（missing_have 与 missing_gap）。
cv_get	获取定制简历的完整文档。
cv_edit	原子性地对定制简历应用一批按路径指定的编辑（由服务端验证；拒绝未经引用支持的陈述）。
cv_render	将定制简历渲染为 PDF，并以 base64 格式的 application/pdf 资源返回。
experience_list	候选人的经历库，包含每项成果的来源信息。cv_edit 的 evidence_id 来源于此处。
experience_add_employment / experience_add_achievement	记录一段任职经历或一项证据。
experience_update_employment / experience_update_achievement	修正一项记录。按字段更新：未指定的内容会保留。
experience_remove_employment / experience_remove_achievement	删除一项记录。无法撤销；必须先清空任职经历。
submit	提交职位以供审核。
my_submissions	查看调用者提交的内容及其状态。
contribute	将职位或公司招聘页面链接提交给目录收录流程。
my_contributions	查看调用者提交的链接和招聘页面及其收录状态。
jobs_add / jobs_edit	审核员：创建／编辑职位（没有相应角色时返回 403）。
submissions_pending	审核员：查看待审核队列。
submission_approve / submission_reject	审核员：批准／驳回提交内容。

筛选条件。 search、market_fit 和 facets 使用相同的市场筛选参数：remote、region、country、city、company、category、role、seniority、employment_type、english_level、exclude_skill、salary_min、visa，以及通用的 facets 映射（{"source": "greenhouse"}），用于指定词汇表中的其他筛选项。使用 facets 工具查找有效取值，不要自行编造。在 search 中，skills 是筛选条件；在 market_fit 中，skills 是待评估的技能集合。

地理范围会扩大。 region、country 和 city 属于同一个 OR 组：region: ["eu"] 与 country: ["IT"] 表示“在欧洲或在意大利”，返回的结果不会比仅指定区域时少。要搜索单个国家，请传入 country 并省略 region。这三个参数指向同一个概念——地点；因此选择两个地点表示“满足任一条件”，这也正是 region: ["eu"] 与 country: ["BR"]（“欧洲或巴西”）组合使用的意义。无法切换为 AND：_mode=and 不适用于地理筛选。 未读参数会被忽略，而不是拒绝请求。 API 不识别的筛选键不会导致请求失败，而是会扩大查询范围。这类键会出现在结果的 ignored 列表中；如果只是单复数用错，还会附上 did_you_mean。search 会将其与 total 一并返回；facets 和 market_fit 只返回单个对象，因此会将结果包装为 {data, ignored}——仅在这种情况下包装，不影响正常调用的返回结构。任何来自包含 ignored 的结果的数字，回答的范围都比所问的问题更广——报告数字前，请使用建议的名称重试。

描述。 search 会读取 API 的 Agent 端点，因此每条命中结果都已包含招聘信息的完整 Markdown 描述——主机无需为每条命中结果都调用一次 job，即可筛选结果集。描述很长，因此请将 limit 设得适中。

证据规则。 库中的每项成就都会记录是谁提出的。cv_import、stated_in_chat 和 manual 表示候选人本人提出，可在简历中引用；agent_inferred 表示模型将其推断并录入记录，不可引用。cv_edit 会拒绝任何缺少指向可引用证据的 evidence_id 的候选人相关声明，因此只有 experience_list 这个工具能让 cv_edit 真正可用。

更正成就不会改变其标签：agent_inferred 成就无论如何改写，都仍不可引用。要使其变为可引用，唯一的方法是询问候选人，然后通过 experience_add_achievement 记录候选人本人的陈述。

删除不可撤销——库中没有撤销功能。必须先清空一个职位，才能删除它，因为删除职位会连同其下的所有成就一起删除。网站支持将两项成就合并为一项，并保留两者的数据。

每个工具都会将原始 API data 作为 JSON 文本返回；API 错误会作为包含 HTTP 状态码的 isError 结果返回（401 错误还会附带身份验证提示）。

开发

npm install
npm test        # vitest: config, client (mock server), facets, tool dispatch
npm run build   # tsc → dist/

许可证

MIT——详见 LICENSE。freehire 后端和 CLI 也采用 MIT 许可证。