freehire MCP сервер

Сервер MCP поверх API вакансий freehire. Он позволяет любому MCP-хосту — Claude Desktop, Claude Code или совместимому агенту — искать, фильтровать и откликаться на IT-вакансии без браузера, аутентифицируясь с помощью персонального API-ключа. Вакансии собираются напрямую с карьерных страниц компаний — более 3,3 млн открытых позиций в 294 тыс. компаний, нормализованных в единую схему и помеченных стеком, уровнем, регионом и форматом работы (актуальные цифры).

Он повторяет freehire CLI: тот же API, те же учетные данные, но в виде MCP-инструментов вместо shell-команд.

Установка

Глобальная установка не требуется — хост запускает его через npx. Добавьте его в конфигурацию MCP вашего хоста (Claude Desktop → Настройки → Разработчик → Изменить конфигурацию или ~/.claude.json для Claude Code):

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

Создайте ключ fhk_… в веб-приложении (freehire.me → меню аккаунта → API-ключи). Если вы уже используете freehire CLI (freehire auth login), вы можете опустить env — сервер читает тот же ~/.freehire/creds.json.

Related MCP server: job-monitor

Аутентификация

Токен и базовый URL API определяются с приоритетом env → ~/.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"] означает «в Европе или в Италии» и возвращает всё, что вернул бы только регион. Чтобы искать в одной стране, передайте country и опустите region. Эти три параметра называют одно понятие — где — поэтому выбор двух мест читается как «либо», что делает region: ["eu"] с country: ["BR"] («Европа или Бразилия») полезным. Нет режима И: _mode=and не применяется к географии.

Неизвестные параметры игнорируются, а не отклоняются. Ключ фильтра, который API не распознаёт, не приводит к ошибке запроса, а расширяет его. Такие ключи возвращаются в списке ignored результата, с did_you_mean, если ошибка была только в грамматическом числе. search сообщает об этом рядом с total; facets и market_fit возвращают один объект, поэтому они оборачивают его как {data, ignored} — и только в этом случае, не меняя форму чистого вызова. Любое число из результата с ignored отвечает на более широкий вопрос, чем заданный — повторите с предложенным именем, прежде чем сообщать о нём.

Описания. search читает агентскую конечную точку API, поэтому каждый результат уже содержит полное описание вакансии в формате 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.

Удаление окончательно — в банке нет отмены. Место должно быть очищено, прежде чем его можно удалить, потому что удаление места удалит все достижения под ним. Объединение двух достижений в одно с сохранением чисел из обоих — на сайте.

Каждый инструмент возвращает необработанные data API в виде JSON-текста; ошибка API становится результатом isError с HTTP-статусом (401 добавляет подсказку об аутентификации).

Разработка

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

Лицензия

MIT — см. LICENSE. Бэкенд и CLI freehire также под MIT.