The hh-mcp server exposes 55 tools for querying hh.ru's API — job vacancies, resumes, applications/ATS, employers, salary stats, and reference dictionaries — for use by an AI agent via MCP.
Vacancy search & details (no token) — search_vacancies (by text, region, role, industry, metro, salary, experience, work format, dates, labels, sorting), get_vacancy, get_similar_vacancies, get_related_vacancies.
Vacancy analytics (token) — get_vacancy_stats, get_vacancy_visitors, get_vacancy_conditions.
Resume search & reads (employer token + paid resume DB) — search_resumes, get_resume (prefer topic_id for scoped/cheaper reads), get_resumes (batch up to 50 via gated budget), collect_vacancy_resumes (walk a vacancy funnel), get_resume_negotiations_history, list_saved_resume_searches, get_saved_resume_search, hh_usage_report.
ATS / applications (employer token) — list_application_collections, list_applications, get_application, get_application_messages, get_negotiations_statistics, get_preferred_negotiations_order.
Employers — public: search_employers, get_employer, get_employer_vacancies; token: list_employer_managers, get_employer_manager, get_manager_resume_limits, get_manager_negotiations_statistics, list_active_vacancies, list_archived_vacancies, list_hidden_vacancies, get_message_template, list_mail_templates, get_employer_vacancy_areas, get_employer_departments, list_employer_addresses.
Reference dictionaries & autocomplete (no token) — get_areas, get_areas_subtree, get_countries, get_professional_roles, get_industries, get_metro, get_languages, get_skills, get_districts, get_dictionaries, plus suggest_positions, suggest_professional_roles, suggest_companies, suggest_areas, suggest_vacancy_search_keyword, suggest_resume_search_keyword, suggest_skill_set.
Salary & account — get_salary_statistics (paid salary bank with token+area, else biased sampling fallback), validate_token (checks HH_ACCESS_TOKEN role).
Operational niceties — raw: true on most tools returns full hh.ru JSON; compact summaries by default; gated resume reads respect rate limits (1.5s spacing, 20/60s window), disk caching, captcha breaker, and a shared budget file; tool surface can be trimmed via HH_TOOLS / HH_TOOLS_EXCLUDE; runs over stdio or Streamable HTTP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hh-mcp найди Python-вакансии в Москве с зарплатой от 250 000 ₽"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Если вы искали, как подключить hh.ru к Claude или другому ИИ-агенту, — этот сервер даёт агенту поиск по вакансиям и резюме, inbox откликов (ATS), карточки работодателей, статистику зарплат и справочники hh.ru по России и СНГ. Спрашиваете «найди Python-вакансии в Москве от 250 000 ₽ на удалёнке» — агент возвращает готовый список с зарплатами и опытом, а не ссылку на выдачу. Поиск вакансий работает без токена; токен нужен для базы резюме и ATS.
По умолчанию ответы приходят компактными сводками, удобными для LLM — передайте raw: true любому инструменту поиска или карточки, чтобы получить полный JSON hh.ru.
Основано на @theyahia/hh-mcp от @theYahia.
Режим | Что доступно | Нужен токен? |
Без токена | Поиск вакансий, вакансия по ID, похожие/связанные вакансии, работодатели, статистика зарплат, регионы, роли, отрасли, метро, страны/языки/навыки/районы, справочники, подсказки, проверка токена | нет |
С токеном | Всё перечисленное + поиск резюме, ATS/отклики, менеджеры, лимиты, архив/скрытые вакансии, статистика вакансий, сохранённые поиски | да ( |
Токен выдаётся на dev.hh.ru/admin. Важно: поиск резюме дополнительно требует аккаунт работодателя с оплаченной подпиской на базу резюме — токены соискателя и анонимные получают 403. ATS/negotiations требуют employer-токен. Проверить возможности своего токена можно инструментом validate_token.
Related MCP server: HeadHunter API MCP Server
{
"mcpServers": {
"hh": {
"command": "npx",
"args": ["-y", "@andrey-tepaykin/hh-mcp"],
"env": {
"HH_ACCESS_TOKEN": "optional-oauth-token"
}
}
}
}claude mcp add hh -- npx -y @andrey-tepaykin/hh-mcp
# С токеном:
claude mcp add hh -e HH_ACCESS_TOKEN=your-token -- npx -y @andrey-tepaykin/hh-mcp{
"servers": {
"hh": {
"command": "npx",
"args": ["-y", "@andrey-tepaykin/hh-mcp"]
}
}
}{
"mcpServers": {
"hh": {
"command": "npx",
"args": ["-y", "@andrey-tepaykin/hh-mcp"]
}
}
}npx @andrey-tepaykin/hh-mcp --http
# или
HTTP_PORT=8080 npx @andrey-tepaykin/hh-mcp --httpЭндпоинт: http://localhost:3000/mcp (POST) · Проверка состояния: http://localhost:3000/health (GET)
HTTP-режим stateless, по умолчанию слушает 127.0.0.1 с включённой защитой от DNS-rebinding. Чтобы открыть его наружу, задайте HOST=0.0.0.0, добавьте свой host/origin в HH_ALLOWED_HOSTS / HH_ALLOWED_ORIGINS и поставьте перед ним собственную аутентификацию.
Переменная | Обяз. | Описание |
| нет | Bearer-токен OAuth 2.0. Нужен для резюме, ATS/откликов и employer-scoped endpoint'ов. |
| нет | Свой |
| нет | Лимит страниц hh.ru при |
| нет | Параллельных гейтед-просмотров резюме (по умолчанию 1). |
| нет | Мин. интервал между стартами гейтед-чтений (по умолчанию 1500). |
| нет | Макс. гейтед-чтений в скользящем окне (по умолчанию 20; |
| нет | Длина скользящего окна (по умолчанию 60000). |
| нет | Shared lock-файл бюджета, окна и breaker'а между процессами; |
| нет | Начальный cooldown breaker'а при captcha (по умолчанию 60000). |
| нет | Потолок cooldown (по умолчанию 600000). |
| нет | Лестница пауз, сек (по умолчанию |
| нет | Длительность осторожного режима после капчи (по умолчанию 600000): интервал ×2, окно ÷2 на 10 чтений. |
| нет | Пауза после пробного чтения и мин. пауза перед повтором 404 в recovery (по умолчанию 5000). |
| нет | Кэш резюме на диске (TTL 24ч; |
| нет | JSONL-ledger гейтед-чтений и лог запросов (по умолчанию выкл.). |
| нет | Метка инстанса в ledger, |
| нет |
|
| нет | Каталог экспорта для |
| нет |
|
| нет | Сколько помнить рабочий путь квоты, не пробуя другой (по умолчанию 3600000). |
| нет | Когда |
| нет |
|
| нет | Базовый URL API (по умолчанию |
| нет | Allow/deny список имён и групп инструментов. CLI: |
| нет | Порт HTTP-режима (по умолчанию 3000). HTTP включается только флагом |
| нет | Интерфейс привязки в HTTP-режиме (по умолчанию |
| нет | Список разрешённых Host через запятую для HTTP-режима (по умолчанию loopback). |
| нет | Список разрешённых Origin через запятую для HTTP-режима. |
См. .env.example.
Любой инструмент поиска или карточки принимает raw: true — тогда вернётся полный JSON hh.ru вместо компактной сводки.
Поверхность режется через HH_TOOLS / HH_TOOLS_EXCLUDE (имена и группы: vacancies, resumes, batch, negotiations, employers, references, salary, diagnostics, validate_token). Профиль для разбора откликов: HH_TOOLS=negotiations,resumes,batch,validate_token,diagnostics.
Инструмент | Описание | Токен? |
| Поиск по ключевым словам, региону, профессиональной роли, отрасли, метро, работодателю, зарплате, опыту, формату работы и типу занятости, периоду ( | нет |
| Полная карточка вакансии: описание, требования, ключевые навыки, контакты | нет |
| Найти вакансии, похожие на заданную | нет |
| Связанные вакансии ( | нет |
| Статистика просмотров/откликов по вакансии | да |
| Посетители вакансии | да |
| Условия публикации вакансий | да |
Инструмент | Описание | Токен? |
| Поиск резюме кандидатов по ключевым словам, региону, роли, зарплате, опыту | да |
| Полное резюме. Если резюме из отклика — всегда передавайте | да |
| Пакетное чтение до 50 резюме через бюджет. Предпочтительно | да |
| Сбор резюме по воронке вакансии → raw JSON + | да |
| История откликов по резюме | да |
| Список сохранённых поисков резюме | да |
| Сохранённый поиск резюме по ID | да |
| Локальный отчёт: ledger/лог, breaker, бюджет, кэш; квота обновляется, если отсутствует или старше | нет |
Инструмент | Описание | Токен? |
| Воронка: счётчики по этапам и подэтапам + | да |
| Список откликов: | да |
| Полная карточка отклика (опыт, релевантность, этап, счётчики сообщений) — без платного | да |
| Переписка с пагинацией ( | да |
| Статистика откликов по работодателю ( | да |
| Предпочтительная сортировка откликов по вакансии | да |
Типичный flow: list_application_collections → list_applications → get_application → при необходимости collect_vacancy_resumes / get_resumes с topic_id (не фан-аут субагентов на голый get_resume). get_application печатает готовую подсказку get_resume … topic_id=….
hh.ru антифродом закрывает быстрые пакетные GET /resumes/{id} капчей (403 captcha_required, type: employer_resume_view). Это не исчерпание квоты resume_view_limits и не проблема OAuth-scope.
Правила сервера (3.0.0+):
Передавайте topic_id (+vacancy_id) для резюме из отклика — scoped-URL; нескоупленный путь считается гейтед. Чтение без topic_id в батче помечается статусом unscoped (платная база), а не ok.
Гейтед-трафик идёт через бюджет: concurrency 1, интервал 1500 мс (±20% jitter) и скользящее окно 20 чтений / 60 с; опционально общий файл HH_BUDGET_FILE на два инстанса. Ретраи 429/5xx/404 заново проходят breaker и берут слот.
При captcha открывается breaker: следующие гейтед-вызовы fail-fast с retry_after_s, без молотьбы API. Состояние breaker'а в общем файле монотонно — один инстанс не может «закрыть» cooldown другого.
После снятия breaker'а — осторожный режим (HH_CAPTCHA_RECOVERY_MS): интервал ×2, окно ÷2 на 10 чтений.
404 на чтение резюме повторяется один раз с паузой; повторный 404 — статус not_found (в кэш не пишется).
Успешные ответы кэшируются на диск (HH_CACHE_DIR); повтор не бьёт в сеть.
Массовый разбор — collect_vacancy_resumes / get_resumes, а не 12 параллельных get_resume.
Капча не решается автоматизацией браузера в этом пакете: подождите 45–120 с или откройте fallback_url вручную.
Обычный трафик: 5 запросов/с. Гейтед-просмотры резюме — отдельный более строгий бюджет (см. выше). Автоповтор на 429/5xx (до 3 попыток); captcha не ретраится циклом 5xx.
Инструмент | Описание | Токен? |
| Поиск компаний по названию и региону | нет |
| Профиль работодателя: описание, отрасли, сайт, число вакансий | нет |
| Активные вакансии работодателя (публичный поиск с | нет |
| Менеджеры аккаунта ( | да |
| Менеджер по ID | да |
| Информативные лимиты просмотра резюме менеджера (счётчик hh.ru может не совпадать с фактом; 404/нули — не сигнал капчи). | да |
| Статистика откликов менеджера | да |
| Опубликованные вакансии своего аккаунта ( | да |
| Архивные вакансии | да |
| Скрытые вакансии | да |
| Шаблон сообщения по отклику | да |
| Почтовые шаблоны работодателя | да |
| Активные регионы вакансий | да |
| Подразделения | да |
| Адреса | да |
Инструмент | Описание | Токен? |
| Дерево регионов и городов ( | нет |
| Регионы и города внутри одного региона — легче, чем всё дерево | нет |
| Список стран | нет |
| Дерево профессиональных ролей с ID | нет |
| Дерево отраслей компаний с ID | нет |
| Станции и линии метро с ID по городу | нет |
| Справочник языков | нет |
| Названия навыков по id ( | нет |
| Районы (опционально по | нет |
| Все справочные данные: валюты, типы занятости, графики, опыт, метки | нет |
| Автодополнение названий должностей ( | нет |
| Автодополнение проф. ролей с ID (для фильтров поиска) | нет |
| Автодополнение названий компаний | нет |
| Автодополнение названий регионов и городов | нет |
| Подсказки ключевых слов поиска вакансий | нет |
| Подсказки ключевых слов поиска резюме | нет |
| Автодополнение навыков | нет |
Инструмент | Описание | Токен? |
| При | для банка — да |
| Проверить, действителен ли | нет |
Найди удалённые вакансии Python-разработчика в Москве от 300 000 рублейПокажи все открытые вакансии Яндекса и дай статистику зарплат по основным ролямСравни зарплаты Senior Backend в Москве и Санкт-Петербурге и предложи вакансии, похожие на самую высокооплачиваемуюПокажи коллекции откликов по вакансии 123456 и список неразобранных откликовgit clone https://github.com/AndreyTepaykin/hh-mcp.git
cd hh-mcp
npm install
npm run build
npm testMIT
Репозиторий: AndreyTepaykin/hh-mcp · npm: @andrey-tepaykin/hh-mcp
Walk a vacancy funnel (collection/sub_collection), fetch each resume with topic_id through the gated budget, write raw JSON + manifest/csv under out_dir (HH_EXPORT_DIR). Bounded by max (default 25) and max_wait_ms; returns an id-based cursor/remaining when truncated (safe when new responses arrive between calls). Prefer this over spawning subagents. Requires HH_ACCESS_TOKEN.
Inputs: vacancy_id (required), max, raw, cursor, +5 more.
Full application card from the negotiations endpoint (candidate, relevant experience, funnel stage, message counters) — prefer over get_resume for screening. Requires HH_ACCESS_TOKEN.
Inputs: id (required), raw.
Paginated chat messages for an application topic (page/per_page, max 50). Requires HH_ACCESS_TOKEN.
Inputs: nid (required), raw, page, per_page.
Get the full tree of regions and cities as id — name lines (pass raw:true for nested JSON). Use to find area IDs for search filters.
Inputs: raw.
Get the regions/cities subtree under one area id (e.g. 113=Russia) — lighter than the full /areas tree.
Inputs: area_id (required), raw.
List countries (id — name) from /areas/countries.
Inputs: raw.
Get all reference dictionaries: currencies, employment types, schedules, experience levels, vacancy labels, and more.
Inputs: no named parameters.
List districts (optionally filtered by area_id). Useful for address/area fine-tuning.
Inputs: raw, area_id.
Get detailed employer profile: description, industries, website, vacancy count.
Inputs: employer_id (required), raw.
List departments for an employer. employer_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN.
Inputs: raw, employer_id.
Get a single employer manager by id. employer_id/manager_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN.
Inputs: raw, manager_id, employer_id.
List active vacancies for a specific employer via public vacancy search (employer_id filter). No token required.
Inputs: employer_id (required), raw, page, per_page.
List active vacancy areas for an employer. Requires HH_ACCESS_TOKEN.
Inputs: employer_id (required), raw.
Get the tree of company industries with IDs. Use to find industry IDs for the search_vacancies industry filter.
Inputs: raw.
List languages (id — name) from /languages.
Inputs: raw.
Get negotiations statistics for a manager. employer_id/manager_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN.
Inputs: raw, manager_id, employer_id.
Informational resume-view limits for a manager (hh.ru counter may not match real views; 404/zeros are not a captcha signal). employer_id/manager_id of the authenticated account can be omitted (resolved from /me). Do not pass 0. Requires HH_ACCESS_TOKEN.
Inputs: raw, manager_id, employer_id.
Get a negotiation message template by id (optionally with topic_id / resume_id / vacancy_id). Requires HH_ACCESS_TOKEN.
Inputs: template (required), raw, topic_id, resume_id, +1 more.
Get metro stations and lines with IDs for a city (city_id), or for all cities. Use to find metro IDs for the search_vacancies metro filter.
Inputs: city_id.
Get employer-level negotiations statistics. Requires employer_id and HH_ACCESS_TOKEN.
Inputs: employer_id (required), raw.
Get the preferred negotiations sort order for a vacancy. Requires HH_ACCESS_TOKEN.
Inputs: vacancy_id (required), raw.
Get the tree of professional roles with IDs. Use to find role IDs for vacancy/resume search and salary stats.
Inputs: raw.
Get full resume details: experience, education, skills, contacts. If the resume came through an отклик, always pass topic_id (+vacancy_id): the unscoped read hits the resume database, consumes a paid view and is the call hh.ru captcha-gates. When HH_REQUIRE_TOPIC is on, unscoped reads require allow_unscoped:true. Requires an EMPLOYER OAuth token + paid resume-database access.
Inputs: resume_id (required), raw, no_cache, topic_id, +2 more.
Get negotiation history for a resume (employer view). Requires HH_ACCESS_TOKEN.
Inputs: resume_id (required), raw.
Safely fetch up to 50 resumes sequentially through the resume-view budget (default ~1.5s spacing, 20 reads/60s window). Preferred input: items:[{resume_id, topic_id}] + vacancy_id for scoped reads; set require_topic:true to never read the paid database. Legacy resume_ids+topics is validated (typo'd keys fail before any request). Reads without topic_id return status unscoped. Pass out_dir to persist payloads (raw/*.json + manifest.json + negotiations.csv). stop_on_captcha default true. max_wait_ms default 90000 (cap 110000). Requires HH_ACCESS_TOKEN.
Inputs: raw, items, topics, out_dir, +6 more.
Salary distribution for a role/region. With HH_ACCESS_TOKEN + area_id, tries paid Банк данных зарплат (/salary_statistics/paid/salary_evaluation/{area_id}); on 401/403/404 or without token/area falls back to sampling vacancy salaries (biased). Optional speciality/employee_level/industry/extend_sources for the bank; text maps to position_name.
Inputs: professional_role_id (required), raw, text, area_id, +5 more.
Get a saved resume search by id. Requires HH_ACCESS_TOKEN.
Inputs: id (required), raw.
Find vacancies similar to a given one. Useful for expanding a candidate's job search.
Inputs: vacancy_id (required), raw, page, per_page.
Resolve skill names by id via /skills (1–50 ids). Use suggest_skill_set to discover ids by name first.
Inputs: id (required), raw.
Get full vacancy details: description, requirements, key skills, contacts, employer info.
Inputs: vacancy_id (required), raw.
Get vacancy publication conditions / constraints for the current employer. Requires HH_ACCESS_TOKEN.
Inputs: raw.
Get employer-facing vacancy statistics (views/responses/invitations). Requires HH_ACCESS_TOKEN.
Inputs: vacancy_id (required), raw.
List visitors who viewed a vacancy. Requires HH_ACCESS_TOKEN.
Inputs: vacancy_id (required), raw, page, per_page.
Local diagnostics: gated-read ledger / JSONL log summary, captcha breaker state, resume budget, cache hit counts. No network.
Inputs: raw.
List published (active) vacancies for the authenticated employer account via /employers/{id}/vacancies/active. Requires HH_ACCESS_TOKEN. For any employer's public vacancies use get_employer_vacancies.
Inputs: employer_id (required), raw, page, per_page.
Vacancy application funnel: per-stage and per-sub-stage counters plus unread (with_updates). Sub-collection ids are inputs for list_applications. Also lists employer_states. Start here before list_applications. Requires HH_ACCESS_TOKEN.
Inputs: vacancy_id (required), raw.
List applications for a vacancy by collection or sub_collection (id/name), with optional with_updates_only (scans collection pages for has_updates; page/per_page are the filtered stream; capped by HH_MAX_SCAN_PAGES), page/per_page/order_by. raw:true returns one unfiltered upstream page. Defaults collection to response. Requires HH_ACCESS_TOKEN.
Inputs: vacancy_id (required), raw, page, order_by, +4 more.
List archived vacancies for an employer. Requires HH_ACCESS_TOKEN.
Inputs: employer_id (required), raw, page, per_page.
List addresses for an employer. Requires HH_ACCESS_TOKEN.
Inputs: employer_id (required), raw.
List managers for an employer account. employer_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN.
Inputs: raw, page, per_page, employer_id.
List employer mail templates. Requires employer_id and HH_ACCESS_TOKEN.
Inputs: employer_id (required), raw.
List saved resume searches for the current employer account. Requires HH_ACCESS_TOKEN.
Inputs: raw, page, per_page.
Search companies/employers on hh.ru by name. Returns company info and open vacancy count.
Inputs: text (required), raw, area, page, +1 more.
Search candidate resumes by keywords, region, professional role, salary, experience. Requires an EMPLOYER OAuth token (HH_ACCESS_TOKEN) AND a paid hh.ru resume-database subscription — applicant/anonymous tokens get 403.
Inputs: raw, area, page, text, +4 more.
Search job vacancies on hh.ru by keywords, region, professional role, industry, metro, salary, experience, employment form, work format, date range and labels. Returns a compact paginated summary (pass raw:true for full JSON).
Inputs: raw, area, page, text, +19 more.
Autocomplete region/city names. Returns matching area suggestions for partial input.
Inputs: text (required), raw.
Autocomplete company names. Returns matching employer suggestions for partial input.
Inputs: text (required), raw.
Autocomplete free-form job titles / positions via /suggests/positions (not role IDs — use suggest_professional_roles for those).
Inputs: text (required), raw.
Autocomplete professional roles with IDs via /suggests/professional_roles. Use for vacancy/resume search filters and salary stats.
Inputs: text (required), raw.
Autocomplete resume-search keywords via /suggests/resume_search_keyword.
Inputs: text (required), raw.
Autocomplete skills via /suggests/skill_set.
Inputs: text (required), raw.
Autocomplete vacancy-search keywords via /suggests/vacancy_search_keyword.
Inputs: text (required), raw.
Check whether HH_ACCESS_TOKEN is valid via /me and report the user role (applicant/employer). Use to diagnose resume-search and ATS access.
Inputs: raw.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 55 tools
Descriptions are detailed and often explicitly say when to prefer one tool over another (e.g., get_application vs get_resume). However, several clusters overlap: get_resumes vs collect_vacancy_resumes vs search_resumes vs get_resume, and list_active/archived/hidden vacancies vs get_employer_vacancies vs search_vacancies. An agent can usually disambiguate with the descriptions, but the sheer number increases misselection risk.
Nearly all tools use snake_case with a verb_noun pattern (get_, list_, search_, suggest_, collect_, validate_). hh_usage_report breaks the verb_noun convention, and a few names are compound or plural, but the overall scheme is predictable and readable.
55 tools far exceeds the 3–15 sweet spot and crosses the 50+ 'extreme mismatch' threshold. While the hh.ru domain is broad, the surface is unwieldy and many list/get endpoints could be consolidated (e.g., vacancy statuses, area lookups), making selection and maintenance burdensome.
The server covers extensive read operations: search, dictionaries, resumes, applications, employer data, and negotiations. However, it lacks write/lifecycle tools such as create/update/delete for vacancies or resumes, apply-to-vacancy, send-message, or status-update actions. Core CRUD coverage is missing, though read-only analysis workflows are well served.
Query professional profiles, search candidates, and get AI-powered summaries and job fit analysis.
Salary and H-1B disclosed-wage data as agent tools.
Jobs, ads, SEO, keywords, YouTube and AliExpress data for AI agents. Runs on Apify.
CareerProof MCP gives AI agents direct access to a professional-grade career and workforce intelligence platform. Two namespaces: atlas_* for HR/TA teams (candidate evaluation, batch shortlisting, competency scoring, interview generation, JD analysis, custom eval frameworks, research reports) and ceevee_* for professionals (CV optimization, career positioning, salary intelligence, market reports). Backed by RAG knowledge from 50+ premium research sources (McKinsey, BCG, HBR, Gartner, WEF)
