freehire MCP 服务器

一个基于 freehire 职位 API 的 MCP 服务器。它让任何 MCP 宿主——Claude Desktop、Claude Code 或兼容的智能体——无需浏览器即可搜索、筛选和申请 IT 职位，并使用个人 API 密钥进行认证。职位发布直接抓取自公司招聘官网——覆盖 294K 家公司的 3.3M+ 个在招职位，规范化为统一结构，并标记了技术栈、资历、地区和工作模式（实时数据）。

它与 freehire CLI 保持一致：相同的 API、相同的凭据，只是以 MCP 工具而非 shell 命令的形式暴露。

安装

无需全局安装——宿主通过 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。

Related MCP server: job-monitor

认证

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

服务器只读取凭据文件（绝不写入——登录仍是 CLI 的职责）。如果未配置令牌，工具会返回明确的“未认证”错误，而不是让服务器启动失败。

工具

筛选器。 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 是一个“或”分组：region: ["eu"] 搭配 country: ["IT"] 表示“在欧洲或意大利”，并返回仅用 region 时本应返回的所有结果。要搜索单个国家，请传入 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 表示由候选人本人断言，可以在 CV 中引用；agent_inferred 表示由模型读入记录，不得引用。cv_edit 会拒绝任何没有 evidence_id 指向可引用证据的关于候选人的陈述，这正是 experience_list 是让 cv_edit 真正可用的工具的原因。

更正一项成就不会改变该标签：agent_inferred 的成就无论怎样改写都仍然不可引用。使其可引用的唯一方法是询问候选人，然后用 experience_add_achievement 记录他们所说的话。

删除是最终的——经历库没有撤销功能。一个工作地点必须先清空才能删除，因为删除它会带走其下所有成就。将两项成就合并为一项并保留两者的数字，这一操作在网站上完成。

每个工具都以 JSON 文本形式返回原始 API data；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 许可。