@theyahia/hh-mcp
An MCP server that gives AI agents access to hh.ru (Russia/CIS job market) through 19 tools.
Search vacancies with filters (keywords, region, role, industry, metro, employer, salary, experience, work format, employment type, date range, labels) and pagination/sorting
Get full vacancy details, including description, skills, contacts, and similar vacancies
Search and retrieve candidate resumes (requires employer token + paid resume database)
Search employers and view employer profiles and their active vacancies
Fetch reference data: areas/regions, professional roles, industries, metro stations, and full dictionaries
Autocomplete job titles, company names, and area/city names
Estimate salary statistics (median, percentiles, min/max) for a role in a region
Validate hh.ru access token and determine account role
Return either compact LLM-friendly summaries or full raw hh.ru JSON via
raw: true
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., "@@theyahia/hh-mcp Find senior backend developer jobs in Moscow with salary over 150k"
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.
MCP-сервер для hh.ru API — 19 инструментов для ИИ-агента: вакансии, резюме, зарплаты
Если вы искали, как подключить hh.ru к Claude или другому ИИ-агенту, — этот сервер даёт агенту поиск по вакансиям и резюме, карточки работодателей, статистику зарплат и справочники hh.ru по России и СНГ. Спрашиваете «найди Python-вакансии в Москве от 250 000 ₽ на удалёнке» — агент возвращает готовый список с зарплатами и опытом, а не ссылку на выдачу. Поиск вакансий работает без токена; токен нужен только для базы резюме.
По умолчанию ответы приходят компактными сводками, удобными для LLM — передайте raw: true любому инструменту поиска или карточки, чтобы получить полный JSON hh.ru.
Часть серии WWmcp от @theYahia.
Два режима
Режим | Что доступно | Нужен токен? |
Без токена | Поиск вакансий, вакансия по ID, похожие вакансии, работодатели, статистика зарплат, регионы, роли, отрасли, метро, справочники, подсказки, проверка токена | нет |
С токеном | Всё перечисленное + поиск резюме, резюме по ID | да ( |
Токен выдаётся на 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-mcpVS 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 и поставьте перед ним собственную аутентификацию.
Переменные окружения
Переменная | Обяз. | Описание |
| нет | Bearer-токен OAuth 2.0. Нужен для эндпоинтов резюме (работодатель + оплаченная база резюме). |
| нет | Свой |
| нет | Порт HTTP-режима (по умолчанию 3000). |
| нет | Интерфейс привязки в HTTP-режиме (по умолчанию |
| нет | Список разрешённых Host через запятую для HTTP-режима (по умолчанию loopback). |
| нет | Список разрешённых Origin через запятую для HTTP-режима. |
См. .env.example.
Инструменты (19)
Любой инструмент поиска или карточки принимает raw: true — тогда вернётся полный JSON hh.ru вместо компактной сводки.
Вакансии
Инструмент | Описание | Токен? |
| Поиск по ключевым словам, региону, профессиональной роли, отрасли, метро, работодателю, зарплате, опыту, формату работы и типу занятости, периоду ( | нет |
| Полная карточка вакансии: описание, требования, ключевые навыки, контакты | нет |
| Найти вакансии, похожие на заданную | нет |
Резюме (токен работодателя + оплаченная база резюме)
Инструмент | Описание | Токен? |
| Поиск резюме кандидатов по ключевым словам, региону, роли, зарплате, опыту | да |
| Полное резюме: опыт, образование, навыки, контакты | да |
Работодатели
Инструмент | Описание | Токен? |
| Поиск компаний по названию и региону | нет |
| Профиль работодателя: описание, отрасли, сайт, число вакансий | нет |
| Активные вакансии конкретного работодателя | нет |
Справочники и подсказки
Инструмент | Описание | Токен? |
| Дерево регионов и городов ( | нет |
| Регионы и города внутри одного региона — легче, чем всё дерево | нет |
| Дерево профессиональных ролей с ID | нет |
| Дерево отраслей компаний с ID | нет |
| Станции и линии метро с ID по городу | нет |
| Все справочные данные: валюты, типы занятости, графики, опыт, метки | нет |
| Автодополнение названий должностей | нет |
| Автодополнение названий компаний | нет |
| Автодополнение названий регионов и городов | нет |
Зарплаты и аккаунт
Инструмент | Описание | Токен? |
| Оценочное распределение зарплат (медиана, P25/P75, мин/макс) по роли в регионе, посчитанное по зарплатам опубликованных вакансий. Выборка смещённая, это не официальные данные рынка. | нет |
| Проверить, действителен ли | нет |
Ограничение частоты запросов
Встроенный лимитер соблюдает ограничение 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
Available Tools
19 toolsget_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Search remote jobs, read full postings, and get application links from Claude, Codex, Cursor, and other compatible MCP clients. Tools: search_jobs, get_job, get_filters. Supports cursor pagination and location, category, skill, seniority, employment type, and salary availability filters. Free, read-only Streamable HTTP; no account or API key required. Posting-based facts; remote does not imply worldwide eligibility. Setup: https://heyrole.ai/developers
Job-posting search (jobicy, HN Who is Hiring, arbeitnow) and US H-1B salary data as agent tools.
Salary and H-1B disclosed-wage data as agent tools.
Web scraping and search, geocoding, IP and domain checks, translation, weather. 15 tools, x402.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.38MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to access and manage HeadHunter job platform data, including vacancies, resumes, negotiations, and employer settings via 167+ tools.5MIT
- FlicenseAqualityDmaintenanceEnables 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.94-
- AlicenseAqualityBmaintenanceEnables 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.7MIT