business-mcp-ru → API hh.ru в ИИ-ассистенте

API hh.ru в ИИ-ассистенте

MCP-сервер для API hh.ru: 133 метода официальной спеки. Вакансии, отклики и приглашения, резюме, справочники, статистика зарплат. Установка одной командой, ключ из dev.hh.ru.

Установка

uvx hh-mcp-ru

Переменные окружения: HH_TOKEN, HH_APP_NAME. Ключи можно не держать в окружении: у сервера есть инструменты управления кабинетами, они кладут ключи в локальный файл с правами 600.

Где взять ключ

dev.hh.ru → Мои приложения → создать приложение → access token. HH_APP_NAME заполняется обязательно: hh отклоняет запросы без внятного User-Agent, и это первая причина непонятных ошибок 400.

Карта методов: 133 метода

Таблица собрана из того же каталога, который сервер исполняет в рантайме (источник: официальная спека api.hh.ru/openapi/specification/public). Класс доступа определяет поведение: чтение идёт сразу, запись и необратимые действия требуют подтверждения.

Раздел	Методов	Чтение	Запись	Необратимое
Работодатель и менеджеры	30	23	5	2
Вакансии	21	12	7	2
Общие справочники	14	6	7	1
Подсказки	11	11	0	0
Отклики и приглашения	10	5	5	0
Сохранённые поиски	6	2	3	1
Статистика зарплат	5	5	0	0
Вебхуки	4	1	2	1
Комментарии к соискателю	4	1	2	1
Резюме	3	3	0	0
Звонки	3	3	0	0
Регионы	3	3	0	0
Токены	2	0	1	1
Учебные заведения	2	2	0	0
Локали	2	2	0	0
Метро	2	2	0	0
Текущий пользователь	1	1	0	0
Аккаунты менеджеров	1	1	0	0
Отрасли	1	1	0	0
Словари	1	1	0	0
Профессиональные роли	1	1	0	0
Языки	1	1	0	0
Навыки	1	1	0	0
Clickme	1	1	0	0
Районы	1	1	0	0
Шаблоны сообщений	1	1	0	0
Условия публикации вакансий	1	1	0	0
Всего	133	92	32	9

Что обычно просят

Выгрузить свои вакансии и отклики за период и свести в таблицу.
Посмотреть статистику зарплат по роли перед публикацией вакансии.
Найти вакансии конкурентов по региону и профессиональной роли.
Ответить кандидатам шаблоном, показав список человеку до отправки.

Как это работает в чате

hh_search_methods("...")   поиск метода словами, а не по имени эндпоинта
hh_describe_method(...)   параметры, пагинация, класс доступа
hh_call_method(...)       вызов; запись спрашивает подтверждение

Частые ошибки и что они значат

400 на любом запросе, хотя токен верный

Первым делом проверьте HH_APP_NAME. hh отклоняет запросы без внятного заголовка HH-User-Agent, а туда подставляется имя приложения и контактный email. Без переменной сервер шлёт значение по умолчанию, и это самая частая причина непонятных четырёхсотых.

403 на методе, который открывается в кабинете

У каждой записи каталога проставлен раздел доступа, и hh_describe_method его показывает. 403 почти всегда значит, что токен выдан на другой тип аккаунта: тридцать методов раздела «Работодатель и менеджеры» соискательским токеном не открываются.

Ответ обрывается на первых двадцати записях

Это не обрыв, а страница. У методов с постраничной выдачей в каталоге указаны параметры пагинации, и hh_fetch_all проходит страницы сам. Если звать hh_call_method напрямую, страницу надо передавать руками.

Частые вопросы

Как получить токен API hh.ru?

dev.hh.ru, раздел «Мои приложения», создать приложение и взять access token. Вместе с токеном сразу заполните HH_APP_NAME: имя приложения и контактный email, без них hh отвечает 400.

Где документация API hh.ru?

Официальная спека лежит открыто: api.hh.ru/openapi/specification/public. Каталог этого сервера собран из неё же, поэтому таблица разделов на этой странице и то, что сервер реально вызывает, это один и тот же файл.

Можно ли откликаться и писать кандидатам через API?

Да, раздел «Отклики и приглашения» это умеет, и такие методы помечены как запись. Перед отправкой сервер обязан спросить подтверждение, поэтому случайной рассылки от лица агента не будет.

Сколько методов hh.ru поддерживает hh-mcp-ru?

133, все с официального хоста api.hh.ru. У каждого метода указаны параметры, пагинация и класс доступа: 92 на чтение, 32 на запись, 9 необратимых.