Job Finder

为任何行业、任何国家寻找工作——从一句话，或从你的简历出发—— 并按你被列入候选名单的真实概率进行排序。

jobfinder daily --query "electrician jobs in Dubai"

你会得到一份放在桌面上的电子表格，最优者在前。运行结束时它会自动打开。

一切都在你的机器上运行。你的简历除了以文本形式通过你自己的密钥发送到 Anthropic 的 API 之外，绝不会离开你的机器；你的搜索词会发送到你已启用的 招聘网站——就像你亲自在那些网站上输入一样。

快速开始

四个步骤。大约需要五分钟。

1. 安装

git clone https://github.com/MajidAli2006/jobfinder.git
cd jobfinder
python3 -m venv .venv
.venv/bin/pip install -e ".[all]"

2. 获取一个 API 密钥

前往 console.anthropic.com/settings/keys， 登录，点击 Create Key，然后复制它。它以 sk-ant- 开头。

这是该工具唯一真正需要的密钥。

3. 将密钥放入名为 .env 的文件中

cp .env.example .env

用任意文本编辑器打开 .env，将你的密钥粘贴在 = 后面，不要加引号， 也不要加空格：

ANTHROPIC_API_KEY=sk-ant-your-key-here

保存即可。.env 已被 git 忽略，因此你的密钥永远不会被提交。

4. 确认一切正常，然后开始搜索

.venv/bin/jobfinder setup
.venv/bin/jobfinder daily --query "warehouse jobs in Leeds"

提示：运行一次 source .venv/bin/activate，之后在本次终端会话中就可以 省略 .venv/bin/ 前缀。

Related MCP server: JobSpy MCP Server

通过 Claude（MCP）使用

这个工具也是一个 MCP 服务器，所以你可以直接让 Claude 帮你搜索。

Claude Code —— 一条命令：

claude mcp add --scope user jobfinder -- /full/path/to/jobFinder/.venv/bin/jobfinder-mcp

将 /full/path/to/jobFinder 替换为你克隆的位置。在该文件夹内运行 pwd 即可获取路径。

Claude Desktop —— 打开 claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "jobfinder": {
      "command": "/full/path/to/jobFinder/.venv/bin/jobfinder-mcp"
    }
  }
}

配置文件位于：

之后重启 Claude Desktop。Cursor 和 Windsurf 在其各自的 MCP 设置中 使用相同的 command 格式。

然后直接问：

"帮我找欧洲的远程 React 合同工作"

有四个工具可用：check_setup（确认密钥是否正常）、 preview_search（在花费任何费用之前查看请求是如何被理解的）、 find_jobs（完整运行——需要几分钟并写入电子表格），以及 list_platforms（哪些招聘网站服务于某个国家）。

API 密钥——你需要什么，不需要什么

即使完全没有密钥，该工具仍然可以搜索 LinkedIn 的公开职位列表、 雇主招聘页面（Greenhouse、Lever、Ashby、Workable 等）、十个远程招聘网站、 Hacker News 的 "Who is hiring" 板块，以及任何发布标准职位标记的地区性网站。

有了 Anthropic 密钥（上面的第 2 步），它还能理解自由文本请求、 读取你的简历，并判断资格和匹配度。没有它你仍然可以搜索，但你必须在 candidate.local.json 中说明要搜索什么，而不是用一句话——参见"故障排除"。

以下所有内容都是可选的。每一项都会增加更多招聘网站。跳过其中任何一项， 工具只会将该来源报告为未使用——它绝不会导致运行失败。

免费密钥，自助获取

注册，复制密钥，粘贴到 .env 中。

访问 Indeed、Glassdoor、Bayt、Naukri 及其他网站

这些网站——以及 Rozee 和 foundit——会用 CAPTCHA 阻止直接请求，但 它们都有意将职位发布到 Google 的职位索引中。因此入口就是 Google 的索引， 而多家供应商出售其授权访问权限。

它们返回的都是相同的职位列表，因为都是 Google 的数据。区别在于价格和 免费额度，而不是覆盖面。选择你喜欢的任何一个，把它的密钥像其他密钥一样 放入 .env——工具会使用它找到的那一个：

使用与你注册网站匹配的变量。 两者不可互换：将 SearchApi.io 的密钥放在 SERPAPI_KEY 中会被拒绝并返回 401 Invalid API key。SerpApi 密钥是 64 位 十六进制字符；SearchApi.io 的密钥较短。如果收到拒绝，请检查密钥是由哪个 网站签发的。运行 jobfinder sources，它会告诉你正在使用哪个供应商。

SERPAPI_KEY=your-key-here

只设置一个。如果两者都存在，则使用第一个配置的供应商，而且两者都不是 必需的——没有它们工具仍然可以运行，只是会跳过这些网站并在运行摘要中说明。

如果你所在国家的主要招聘网站不在上面的免费列表中，那么这个密钥值得拥有： 它可以在任何国家访问这些网站。覆盖面确实因国家和搜索措辞而异——Google 的 索引中有大量巴基斯坦的 "software engineer" 和阿联酋的 "full stack developer" 职位，但对某些其他组合则完全没有结果。空结果会如实报告，而不是当作密钥 故障。

需要审批

INDEED_PUBLISHER_ID、ZIPRECRUITER_API_KEY、SEEK_API_KEY、 STEPSTONE_API_KEY、BAYT_API_KEY、NAUKRI_API_KEY、ROZEE_API_KEY—— 这些是需要先获得批准的合作伙伴计划。大多数人不需要它们；SerpApi 密钥 就能访问相同的职位列表。

要查看哪些平台服务于你的国家以及它们需要哪些密钥：

jobfinder setup --region Nigeria

密钥放在哪里

以下任意一种，任你选择：

1. 你自己命名的文件，通过 JOBFINDER_ENV=/path/to/your.env

2. 运行命令所在文件夹中的 .env

3. ~/.jobfinder/.env —— 如果你想为每个项目使用同一组密钥，这是个好选择

4. 项目文件夹中的 .env

所有文件都会被读取，并且会合并。 对于在多个文件中设置的密钥， 列表中位置靠前的优先；只有较低位置文件才有的密钥仍然会被读取。 因此你可以将共享密钥放在 ~/.jobfinder/.env 中，将每个项目特有的密钥 放在项目的 .env 中。

真实的环境变量优先于所有文件，所以 export ADZUNA_APP_ID=... 优先。 注意反向不成立：在 shell 中取消设置变量不会隐藏 .env 文件中定义的 密钥。格式是每行一个 KEY=value，不加引号：

ANTHROPIC_API_KEY=sk-ant-...
ADZUNA_APP_ID=12345678
ADZUNA_APP_KEY=abcdef...

日常使用

用通俗的语言说出你想要什么。 无需配置过滤器：

jobfinder daily --query "plumber jobs in Lagos"
jobfinder daily --query "remote React contract, Europe"
jobfinder daily --query "part time warehouse work near Leeds"
jobfinder daily --query "graduate marketing internship, London"

或者把你的简历交给它，让它自己判断你做什么工作：

jobfinder daily --cv ~/cv.pdf
jobfinder daily --cv ~/cv.pdf --query "only remote, minimum £45k"

简历在你的机器上被读取。只有文本被发送到 Anthropic，用于构建你的搜索 画像并评估每条广告的匹配度。

常用参数：

以上每个参数都适用于任何国家。--region 接受国家、城市、本地名称或列表—— "uae"、"Deutschland"、"Lagos"、"USA, UK" 都能解析。

关于 --min-salary： 未公布薪资的广告会被保留，标记为 "未公布薪资"，因为无法证明其低于你的底线。如果你不想看到这些广告， 请添加 --require-salary。如果你的请求本身指定了金额—— --query "electrician jobs, minimum $60k"——未公布薪资的广告会被移到 Prospects 工作表中。

你会得到什么

~/Desktop/job finder/ 中的一份电子表格，包含十三个工作表：Quick Apply （仅基本信息）、Hot Leads、All Qualified Jobs，然后按全职、兼职、 合同、自由职业、初创公司和合作伙伴关系拆分，以及 Prospects（资格不明 ——值得询问）、Long Shots（符合条件，但回复概率低）、 Companies & Contacts，以及一个显示过滤内容和原因的 Search Summary。

相同的数据还会以 .csv、.json 和可浏览的 .html 页面形式写入旁边。

匹配百分比是对被列入候选名单的估计，而不是关键词重叠。 你的简历匹配度 设定上限；在此基础上，估计值会根据广告所揭示的竞争情况而变化。每一行都在 "Why this rank" 列中显示其自身的计算逻辑：

fit 87 × 1.05 = 91 — applicant count not published (-4%) · posted in the
last 24 hours (+3%) · scoped to United Kingdom, smaller pool (+6%) ·
applying straight into the employer's own system (+5%)

因此，有 200 个申请者的完美匹配会排在还没人发现的好匹配之下——这是关于 你的时间花在哪里的诚实答案。

其他命令

jobfinder setup                 # which keys are set, which are missing
jobfinder setup --region India  # what serves a particular country
jobfinder sources               # every connector and its status
jobfinder sources --test        # live-check every configured key
jobfinder status                # what previous runs found
jobfinder platforms --region Kenya
jobfinder platforms --region Kenya --trade "solar installer"
jobfinder check --title "..." --description "..."   # why one advert passed or failed

check 还接受 --company、--location 和 --url，使其能够判断雇主、 资格条件以及你将如何申请，而不仅仅是措辞。

要让某个搜索成为你的默认搜索，以便裸运行 jobfinder daily 即可执行它， 请在项目文件夹中创建 candidate.local.json：

{
  "home_country": "Nigeria",
  "default_search": {
    "label": "Electrical",
    "query": "electrician jobs in Lagos",
    "core_terms": ["electrician", "electrical"]
  }
}

它已被 git 忽略。没有它，裸运行 jobfinder daily 会询问要搜索什么， 而不是自行猜测。

故障排除

"我不知道该找什么样的工作" —— 给它一个 --query 或 --cv。 它不会为你凭空发明一个搜索。

"自定义搜索需要 Claude 判断层" —— 自由文本 --query 必须先由模型 读取才能进行搜索，因此这需要 ANTHROPIC_API_KEY。运行会以退出码 1 停止 并且不写入任何报告。要么设置密钥，要么按照下面的示例在 candidate.local.json 中自行说明搜索内容。

未找到职位 — 使用 --days 30 扩大时间范围，检查你的国家是否拼写完整，并运行 jobfinder setup --region <你的国家> 查看为你服务的站点是否需要你尚未设置的密钥。

"ANTHROPIC_API_KEY 未设置" — .env 文件可能不在工具查找的位置，或者密钥带有引号。运行 jobfinder setup 查看它找到了什么。请记住文件必须命名为 .env，而不是 env 或 .env.txt。

在 Windows 上无反应 — 使用 pip install -e ".[all]" 安装，而不是直接从源码运行；Windows 需要捆绑的 tzdata 包。

想在设置任何密钥之前先看看效果？ 自由文本 --query 需要 Anthropic 密钥，因为总得有人把你的句子读出来并转换成搜索条件。想完全不使用任何密钥运行，就直接把搜索条件写进 candidate.local.json 项目文件夹中：

{
  "default_search": {
    "label": "Warehouse",
    "query": "warehouse operative",
    "core_terms": ["warehouse", "forklift"]
  }
}

然后针对捆绑的示例招聘广告运行：

jobfinder daily --offline --no-llm

这样就能生成完整的电子表格，全程无需联系任何外部服务。

开发

.venv/bin/pip install -e ".[all,dev]"
.venv/bin/python -m pytest tests/ -q      # 661 tests, fully offline
.venv/bin/ruff check job_agent/ tests/

测试不需要网络，也不需要任何密钥。

隐私

你的简历文件只保存在你的机器上——它仅在本地被读取，只有提取出的文本会被发送到 Anthropic 的 API，使用你自己的密钥，用于构建你的搜索画像和判断匹配度。招聘广告的文本也会发送到同一个 API，用途相同，除此之外不会发送到任何其他地方。

你的搜索词会发送到你启用的招聘网站，因为搜索机制就是这样运作的——和你手动在那些网站上输入的词完全一样。如果未设置任何密钥，则意味着使用 LinkedIn 的公开搜索和开放的招聘网站。运行 jobfinder sources 可以查看当前实际启用了哪些来源。

本工具不会向作者发送任何数据，也不包含任何遥测功能。API 密钥从 .env 文件中读取，该文件已被 git 忽略，并且密钥会从日志和错误信息中被清除——即使某个请求因携带密钥而失败，该密钥也会在打印前被脱敏处理。