freehire MCP 서버

freehire 채용 API 위에 구동되는 MCP 서버입니다. 모든 MCP 호스트(Claude Desktop, Claude Code, 또는 호환되는 에이전트)가 브라우저 없이도 개인 API 키로 인증하여 IT 직무를 검색·필터링·지원할 수 있게 해줍니다. 채용 공고는 기업 채용 게시판에서 직접 크롤링되어, 294K개 기업의 3.3M+ 오픈 포지션을 단일 스키마로 정규화하고 기술 스택, 경력, 지역, 근무 형태로 태그합니다(실시간 수치).

freehire CLI를 미러링한 서버입니다. 같은 API, 같은 자격 증명을 사용하며 셸 명령어 대신 MCP 도구로 노출합니다.

설치

전역 설치가 필요 없습니다. 호스트가 npx로 실행합니다. 호스트의 MCP 구성에 추가하세요(Claude Desktop → 설정 → 개발자 → 구성 편집, 또는 Claude Code라면 ~/.claude.json):

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

웹 앱(freehire.me → 계정 메뉴 → API 키)에서 fhk_… 키를 생성하세요. 이미 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는 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}로 래핑합니다. 그리고 그 경우만 그렇게 하므로 정상 호출의 shape은 변하지 않습니다. ignored가 포함된 결과의 어떤 수치든 원래 질문보다 더 넓은 질문에 대한 답입니다. 보고하기 전에 앞서 알려준 이름으로 다시 시도하세요.

설명. search는 API의 agent 엔드포인트를 읽으므로 각 결과가 이미 전체 공고 설명을 마크다운으로 포함합니다. 호스트는 각 결과마다 job을 호출하지 않고도 결과 집합을 사전 검토할 수 있습니다. 설명이 길므로 limit은 적당히 유지하세요.

증거 규칙. 뱅크의 모든 성과(achievement)는 이를 단언한 주체를 함께 기록합니다. cv_import, stated_in_chat, manual은 후보자가 직접 단언한 것이므로 CV에서 인용할 수 있습니다. agent_inferred는 모델이 읽어 넣은 것이므로 인용할 수 없습니다. cv_edit은 인용 가능한 증거를 가리키는 evidence_id 없이 후보자에 관한 주장을 거부합니다. 바로 그 때문에 experience_list가 cv_edit을 실제로 사용 가능하게 만드는 도구입니다.

성과를 수정해도 그 표시는 바뀌지 않습니다: agent_inferred인 것은 문구를 어떻게 바꿔도 인용 불가로 남습니다. 인용 가능하게 되는 유일한 방법은 후보자에게 물은 뒤 그들이 말한 내용을 experience_add_achievement으로 기록하는 것입니다.

삭제는 되돌릴 수 없습니다. 뱅크에는 실행 취소가 없습니다. 근무지/근무처는 먼저 비워야 삭제할 수 있습니다. 그 요소를 통째로 삭제하면 포함된 모든 성과를 함께 지워지기 때문입니다. 두 성과를 하나로 합쳐는 기능(양측의 숫자 유지)은 사이트에서 제공합니다.

각 도구는 원본 API data를 JSON 텍스트로 반환합니다. API 오류는 isError 결과가 되어 HTTP 상태를 담고 있습니다(401에는 인증 힌트 포함).

개발

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

라이선스

MTT — LICENSE 참고. freehire 백엔드와 CLI도 MIT입니다.