MCP-сервер для hh.ru API — 19 инструментов для ИИ-агента: вакансии, резюме, зарплаты
Если вы искали, как подключить hh.ru к Claude или другому ИИ-агенту, — этот сервер даёт агенту поиск по вакансиям и резюме, карточки работодателей, статистику зарплат и справочники hh.ru по России и СНГ. Спрашиваете «найди Python-вакансии в Москве от 250 000 ₽ на удалёнке» — агент возвращает готовый список с зарплатами и опытом, а не ссылку на выдачу. Поиск вакансий работает без токена; токен нужен только для базы резюме.
По умолчанию ответы приходят компактными сводками, удобными для LLM — передайте raw: true любому инструменту поиска или карточки, чтобы получить полный JSON hh.ru.
Часть серии WWmcp от @theYahia.
Два режима
| Режим | Что доступно | Нужен токен? |
|---|
| Без токена | Поиск вакансий, вакансия по ID, похожие вакансии, работодатели, статистика зарплат, регионы, роли, отрасли, метро, справочники, подсказки, проверка токена | нет |
| С токеном | Всё перечисленное + поиск резюме, резюме по ID | да (HH_ACCESS_TOKEN) |
Токен выдаётся на dev.hh.ru/admin. Важно: поиск резюме дополнительно требует аккаунт работодателя с оплаченной подпиской на базу резюме — токены соискателя и анонимные получают 403. Проверить возможности своего токена можно инструментом validate_token.
Установка
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