Skip to main content
Glama
@theyahia/hh-mcp

@theyahia/hh-mcp

by theYahia

MCP-сервер для hh.ru API — 19 инструментов для ИИ-агента: вакансии, резюме, зарплаты

Если вы искали, как подключить hh.ru к Claude или другому ИИ-агенту, — этот сервер даёт агенту поиск по вакансиям и резюме, карточки работодателей, статистику зарплат и справочники hh.ru по России и СНГ. Спрашиваете «найди Python-вакансии в Москве от 250 000 ₽ на удалёнке» — агент возвращает готовый список с зарплатами и опытом, а не ссылку на выдачу. Поиск вакансий работает без токена; токен нужен только для базы резюме.

npm CI License: MIT

Демонстрация: вопрос «найди Python-вакансии в Москве от 250 000 ₽ на удалёнке» — агент вызывает search_vacancies и отвечает списком вакансий

По умолчанию ответы приходят компактными сводками, удобными для LLM — передайте raw: true любому инструменту поиска или карточки, чтобы получить полный JSON hh.ru.

Часть серии WWmcp от @theYahia.

Два режима

Режим

Что доступно

Нужен токен?

Без токена

Поиск вакансий, вакансия по ID, похожие вакансии, работодатели, статистика зарплат, регионы, роли, отрасли, метро, справочники, подсказки, проверка токена

нет

С токеном

Всё перечисленное + поиск резюме, резюме по ID

да (HH_ACCESS_TOKEN)

Токен выдаётся на dev.hh.ru/admin. Важно: поиск резюме дополнительно требует аккаунт работодателя с оплаченной подпиской на базу резюме — токены соискателя и анонимные получают 403. Проверить возможности своего токена можно инструментом validate_token.

Related MCP server: HeadHunter API MCP Server

Установка

Claude Desktop

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": ["-y", "@theyahia/hh-mcp"],
      "env": {
        "HH_ACCESS_TOKEN": "optional-oauth-token"
      }
    }
  }
}

Claude Code

claude mcp add hh -- npx -y @theyahia/hh-mcp
# С токеном:
claude mcp add hh -e HH_ACCESS_TOKEN=your-token -- npx -y @theyahia/hh-mcp

VS Code / Cursor

{
  "servers": {
    "hh": {
      "command": "npx",
      "args": ["-y", "@theyahia/hh-mcp"]
    }
  }
}

Windsurf

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": ["-y", "@theyahia/hh-mcp"]
    }
  }
}

Режим HTTP (Streamable HTTP)

npx @theyahia/hh-mcp --http
# или
HTTP_PORT=8080 npx @theyahia/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 и поставьте перед ним собственную аутентификацию.

Переменные окружения

Переменная

Обяз.

Описание

HH_ACCESS_TOKEN

нет

Bearer-токен OAuth 2.0. Нужен для эндпоинтов резюме (работодатель + оплаченная база резюме).

HH_USER_AGENT

нет

Свой HH-User-Agent (hh.ru его требует). Рекомендуемый формат: your-app/1.0 (you@example.com).

HTTP_PORT / PORT

нет

Порт HTTP-режима (по умолчанию 3000).

HOST

нет

Интерфейс привязки в HTTP-режиме (по умолчанию 127.0.0.1).

HH_ALLOWED_HOSTS

нет

Список разрешённых Host через запятую для HTTP-режима (по умолчанию loopback).

HH_ALLOWED_ORIGINS

нет

Список разрешённых Origin через запятую для HTTP-режима.

См. .env.example.

Инструменты (19)

Любой инструмент поиска или карточки принимает raw: true — тогда вернётся полный JSON hh.ru вместо компактной сводки.

Вакансии

Инструмент

Описание

Токен?

search_vacancies

Поиск по ключевым словам, региону, профессиональной роли, отрасли, метро, работодателю, зарплате, опыту, формату работы и типу занятости, периоду (period или date_from/date_to), меткам и полю поиска, с сортировкой и пагинацией

нет

get_vacancy

Полная карточка вакансии: описание, требования, ключевые навыки, контакты

нет

get_similar_vacancies

Найти вакансии, похожие на заданную

нет

Резюме (токен работодателя + оплаченная база резюме)

Инструмент

Описание

Токен?

search_resumes

Поиск резюме кандидатов по ключевым словам, региону, роли, зарплате, опыту

да

get_resume

Полное резюме: опыт, образование, навыки, контакты

да

Работодатели

Инструмент

Описание

Токен?

search_employers

Поиск компаний по названию и региону

нет

get_employer

Профиль работодателя: описание, отрасли, сайт, число вакансий

нет

get_employer_vacancies

Активные вакансии конкретного работодателя

нет

Справочники и подсказки

Инструмент

Описание

Токен?

get_areas

Дерево регионов и городов (id — название)

нет

get_areas_subtree

Регионы и города внутри одного региона — легче, чем всё дерево

нет

get_professional_roles

Дерево профессиональных ролей с ID

нет

get_industries

Дерево отраслей компаний с ID

нет

get_metro

Станции и линии метро с ID по городу

нет

get_dictionaries

Все справочные данные: валюты, типы занятости, графики, опыт, метки

нет

suggest_positions

Автодополнение названий должностей

нет

suggest_companies

Автодополнение названий компаний

нет

suggest_areas

Автодополнение названий регионов и городов

нет

Зарплаты и аккаунт

Инструмент

Описание

Токен?

get_salary_statistics

Оценочное распределение зарплат (медиана, P25/P75, мин/макс) по роли в регионе, посчитанное по зарплатам опубликованных вакансий. Выборка смещённая, это не официальные данные рынка.

нет

validate_token

Проверить, действителен ли HH_ACCESS_TOKEN (через /me), и показать роль аккаунта

нет

Ограничение частоты запросов

Встроенный лимитер соблюдает ограничение API hh.ru — 5 запросов в секунду. Автоматический повтор с экспоненциальной задержкой на ошибках 429 и 5xx (до 3 попыток). Учтите: лимитер общий на процесс, поэтому в общем HTTP-режиме все клиенты делят один бюджет 5 запросов/сек.

Демо-промпты

Найди удалённые вакансии Python-разработчика в Москве от 300 000 рублей
Покажи все открытые вакансии Яндекса и дай статистику зарплат по основным ролям
Сравни зарплаты Senior Backend в Москве и Санкт-Петербурге и предложи вакансии, похожие на самую высокооплачиваемую

Разработка

git clone https://github.com/theYahia/hh-mcp.git
cd hh-mcp
npm install
npm run build
npm test

Справочник API

Лицензия

MIT


Часть WWmcp · Telegram: @vhodvai

Available Tools

19 tools
get_areasA

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_areas_subtreeA

Get the regions/cities subtree under one area id (e.g. 113=Russia) — lighter than the full /areas tree.

Inputs: area_id (required), raw.

get_dictionariesA

Get all reference dictionaries: currencies, employment types, schedules, experience levels, vacancy labels, and more.

Inputs: no named parameters.

get_employerA

Get detailed employer profile: description, industries, website, vacancy count.

Inputs: employer_id (required), raw.

get_employer_vacanciesC

List active vacancies for a specific employer.

Inputs: employer_id (required), raw, page, per_page.

get_industriesA

Get the tree of company industries with IDs. Use to find industry IDs for the search_vacancies industry filter.

Inputs: raw.

get_metroA

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_professional_rolesA

Get the tree of professional roles with IDs. Use to find role IDs for vacancy/resume search and salary stats.

Inputs: raw.

get_resumeA

Get full resume details: experience, education, skills, contacts. Requires an EMPLOYER OAuth token + paid resume-database access.

Inputs: resume_id (required), raw.

get_salary_statisticsA

Estimate salary distribution (median, P25/P75, min/max) for a professional role in a region by sampling posted vacancy salaries client-side. Biased sample (only vacancies that disclose salary) — not official market data.

Inputs: professional_role_id (required), raw, text, area_id, +1 more.

get_similar_vacanciesB

Find vacancies similar to a given one. Useful for expanding a candidate's job search.

Inputs: vacancy_id (required), raw, page, per_page.

get_vacancyB

Get full vacancy details: description, requirements, key skills, contacts, employer info.

Inputs: vacancy_id (required), raw.

search_employersA

Search companies/employers on hh.ru by name. Returns company info and open vacancy count.

Inputs: text (required), raw, area, page, +1 more.

search_resumesA

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_vacanciesA

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.

suggest_areasA

Autocomplete region/city names. Returns matching area suggestions for partial input.

Inputs: text (required), raw.

suggest_companiesB

Autocomplete company names. Returns matching employer suggestions for partial input.

Inputs: text (required), raw.

suggest_positionsA

Autocomplete job titles / professional roles. Returns matching role suggestions for partial input.

Inputs: text (required), raw.

validate_tokenA

Check whether HH_ACCESS_TOKEN is valid via /me and report the user role (applicant/employer). Use to diagnose resume-search access.

Inputs: raw.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: search/get for vacancies, resumes, employers, plus reference data and suggestions. Even similar tools like get_areas vs get_areas_subtree have clearly separated purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (search_vacancies, get_vacancy, suggest_areas). No mixing of conventions or vague verbs.

    Tool Count4/5

    19 tools is on the higher end but well-justified for a comprehensive job API covering search, retrieval, suggestions, and reference data. Not excessive enough to be a problem.

    Completeness5/5

    The tool surface covers all major read-only operations for hh.ru: vacancy/resume/employer search and retrieval, similar vacancies, salary stats, and reference dictionaries. No obvious gaps for the intended purpose.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to search job vacancies, manage resumes, and apply to jobs on HeadHunter (hh.ru), Russia's largest job search platform. Includes OAuth 2.0 integration for secure job applications and an automated vacancy hunter agent with intelligent matching.
      38
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI assistants to access and manage HeadHunter job platform data, including vacancies, resumes, negotiations, and employer settings via 167+ tools.
      5
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables to interact with hh.ru (a Russian job platform) through browser automation, allowing users to search for jobs, manage resumes, apply to vacancies with cover letters, and track application statuses via natural language.
      9
      4
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables LLM agents to query and analyze hh.ru job vacancies via full-text and semantic search, with tools for vacancy lookup, skill statistics, market overview, and candidate profile comparison.
      7
      MIT