Job Finder

어떤 직종이든, 어떤 나라에서든 일자리를 찾아드립니다 — 문장 하나로, 또는 이력서로 — 그리고 실제로 서류 통과할 가능성에 따라 순위를 매깁니다.

jobfinder daily --query "electrician jobs in Dubai"

바탕화면에 스프레드시트가 생기고, 가장 유망한 순서로 정렬됩니다. 실행이 끝나면 자동으로 열립니다.

모든 작업은 사용자 컴퓨터에서 실행됩니다. 이력서는 사용자 본인의 키로 Anthropic API에 텍스트로 전송되는 경우를 제외하고는 절대 컴퓨터 밖으로 나가지 않으며, 검색어는 사용자가 활성화한 구인 사이트로 전송됩니다 — 해당 사이트에 직접 입력한 것과 똑같이 처리됩니다.

빠른 시작

네 단계입니다. 약 5분 정도 걸립니다.

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-ignored 처리되므로 키가 커밋될 일이 없습니다.

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 등), 10개의 원격 근무 구인 사이트, Hacker News "Who is hiring", 그리고 표준 채용 마크업을 게시하는 모든 지역 구인 사이트를 검색합니다.

Anthropic 키가 있으면 (위 2단계), 자유 형식 텍스트 요청을 이해하고, 이력서를 읽고, 자격 여부와 적합성을 판단합니다. 키가 없어도 검색은 가능하지만, 문장 대신 candidate.local.json에 무엇을 찾을지 직접 명시해야 합니다 — Troubleshooting 참조.

아래의 모든 것은 선택 사항입니다. 각각은 더 많은 구인 사이트를 추가합니다. 어느 것이든 건너뛰면 해당 소스는 사용되지 않은 것으로 보고될 뿐이며, 실행이 실패하지는 않습니다.

무료 키, 셀프 서비스

가입하고, 키를 복사하고, .env에 붙여넣으세요.

Indeed, Glassdoor, Bayt, Naukri 등에 접근하기

이들 사이트 — Rozee와 foundit 포함 — 는 CAPTCHA로 직접 요청을 차단하지만, 모두 의도적으로 Google의 채용 인덱스에 게시합니다. 따라서 접근 경로는 Google의 인덱스이며, 여러 업체가 이에 대한 라이선스 접근 권한을 판매합니다.

모두 동일한 채용공고를 반환합니다. 전부 Google 데이터이기 때문입니다. 선택 기준은 커버리지가 아니라 가격과 무료 할당량입니다. 원하는 것을 선택하고 다른 키와 똑같이 .env에 넣으면 됩니다 — 도구는 발견된 키 중 하나를 사용합니다:

가입한 곳에 맞는 변수를 사용하세요. 둘은 서로 바꿔 쓸 수 없습니다: SearchApi.io 키를 SERPAPI_KEY에 넣으면 401 Invalid API key로 거부됩니다. SerpApi 키는 64자 16진수이고, SearchApi.io 키는 더 짧습니다. 거부 메시지가 뜨면 어느 사이트에서 키를 발급받았는지 확인하세요. jobfinder sources를 실행하면 현재 어떤 업체를 사용 중인지 알려줍니다.

SERPAPI_KEY=your-key-here

하나만 설정하세요. 둘 다 있으면 먼저 구성된 업체가 사용되며, 둘 다 없어도 문제없습니다 — 도구는 계속 실행되고 해당 사이트를 건너뛰며 실행 요약에 그렇게 표시합니다.

위의 무료 목록에 해당 국가의 주요 구인 사이트가 없다면, 이 키가 유용합니다: 어떤 국가에서든 이들 사이트에 접근할 수 있습니다. 커버리지는 국가와 검색어 표현에 따라 다릅니다 — Google 인덱스에는 파키스탄의 "software engineer"와 UAE의 "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=...가 이깁니다. 반대는 성립하지 않습니다: 셸에서 변수를 해제해도 .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 관련: 급여를 게시하지 않은 채용공고는 유지되며 "Pay not published"로 표시됩니다. 급여 하한선 미만임을 증명할 수 없기 때문입니다. 그러한 항목을 아예 보고 싶지 않다면 --require-salary를 추가하세요. 요청 자체에 금액이 명시된 경우 — --query "electrician jobs, minimum $60k" — 게시된 급여가 없는 채용공고는 Prospects 시트로 이동합니다.

결과물

~/Desktop/job finder/에 스프레드시트가 생성되며, 13개의 시트가 있습니다: Quick Apply (핵심 정보만), Hot Leads, All Qualified Jobs, 그 다음 Full Time, Part Time, Contract, Freelance, Startups, Partnerships별 분류, 그리고 Prospects (자격 여부 불명확 — 문의할 가치 있음), Long Shots (자격은 되지만 답변 가능성이 낮음), Companies & Contacts, 그리고 무엇이 어떤 이유로 필터링되었는지 보여주는 Search Summary가 있습니다.

동일한 데이터가 .csv, .json, 그리고 탐색 가능한 .html 페이지로도 함께 작성됩니다.

Match %는 키워드 일치율이 아니라 서류 통과 가능성의 추정치입니다. 이력서 적합도가 상한선을 설정하고, 거기서부터 채용공고가 드러내는 경쟁 상황에 따라 추정치가 움직입니다. 모든 행은 "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-ignored 처리됩니다. 이것이 없으면 jobfinder daily는 추측하지 않고 무엇을 찾을지 묻습니다.

문제 해결

"어떤 종류의 일을 찾아야 할지 모르겠다" — --query 또는 --cv를 주세요. 도구가 검색을 임의로 만들어내지는 않습니다.

"A custom search needs the Claude judgement layer" — 자유 형식 텍스트 --query는 검색되기 전에 모델이 읽어야 하므로 ANTHROPIC_API_KEY가 필요합니다. 실행은 종료 코드 1로 중단되고 보고서를 작성하지 않습니다. 키를 설정하거나, 아래와 같이 candidate.local.json에 검색어를 직접 명시하세요.

작업을 찾을 수 없음 — --days 30으로 기간을 넓히고, 국가 이름이 전체로 철자되었는지 확인하고, jobfinder setup --region <your country>를 실행하여 해당 사이트가 설정하지 않은 키를 필요로 하는지 확인하세요.

"ANTHROPIC_API_KEY is not set" — .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/

테스트에는 키나 네트워크 액세스가 필요 없습니다.

개인정보 보호

귀하의 CV 파일은 귀하의 컴퓨터에 남아 있습니다 — 로컬에서 읽히며, 추출된 텍스트만 귀하의 키로 Anthropic API로 전송되어 검색 프로필을 구축하고 적합성을 판단합니다. 광고 텍스트도 같은 목적으로 같은 API로 전송되며, 다른 곳으로는 전송되지 않습니다.

검색어는 활성화한 채용 게시판으로 전송됩니다. 검색이 그렇게 작동하기 때문입니다 — 해당 사이트에 입력할 것과 같은 단어입니다. 키가 설정되지 않은 경우, 이는 LinkedIn의 공개 검색과 공개 채용 게시판을 의미합니다. jobfinder sources를 실행하여 정확히 어떤 것이 활성화되어 있는지 확인하세요.

이 도구의 작성자에게는 아무 것도 전송되지 않으며, 텔레메트리도 없습니다. API 키는 git에서 무시되는 .env에서 읽히며, 로그와 오류 메시지에서 제거됩니다 — URL에 키가 포함된 실패한 요청은 출력되기 전에 삭제됩니다.