hh-mcp-ru
API hh.ru для ИИ-ассистентов: вакансии, отклики и приглашения, резюме, справочники, статистика зарплат. Каталог из официальной спеки, у каждого метода класс доступа.
Каталог собран из первоисточника (официальная спека api.hh.ru/openapi/specification/public) и лежит в репозитории как
hh_mcp/endpoints.yaml: 133 метода, из них 92 на чтение,
32 на запись и 9 необратимых. Сервер исполняет ровно этот файл,
поэтому таблица ниже не может разойтись с кодом.
Установка
Два пути, выбирайте по тому, есть ли у вас терминал.
Без терминала: файл .mcpb
Скачайте hh-mcp-ru-vX.Y.Z.mcpb со страницы релизов
и откройте двойным щелчком. Claude Desktop поставит сервер сам и спросит ключи
в отдельном окне, в конфиг лезть не придётся. Нужен Python 3.10 или новее:
зависимости сервер доставит себе при первом запуске.
В терминале
Claude Desktop, claude_desktop_config.json:
{
"mcpServers": {
"hh-mcp": {
"command": "uvx",
"args": ["hh-mcp-ru"],
"env": { "HH_TOKEN": "...", "HH_APP_NAME": "..." }
}
}
}
Ключи
dev.hh.ru → Мои приложения → создать приложение → access token. HH_APP_NAME заполняется обязательно: hh отклоняет запросы без внятного User-Agent, и это первая причина непонятных ошибок 400.
| переменная | секрет | что это |
|---|
HH_TOKEN | да | Токен приложения hh.ru (dev.hh.ru → Мои приложения). |
HH_APP_NAME | нет | Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы. |
Ключи можно не держать в окружении: сервер умеет кабинеты и кладёт их в
~/.ru-mcp/cabinets.json с правами 600, вне репозитория.
Карта методов
| раздел | методов | чтение | запись | необратимое |
|---|
| Работодатель и менеджеры | 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_get_vacancies GET /vacancies чтение
hh_get_vacancies_related_to_vacancy GET /vacancies/{vacancy_id}/related_vacancies чтение
hh_get_vacancies_similar_to_vacancy GET /vacancies/{vacancy_id}/similar_vacancies чтение
hh_describe_method("hh_get_vacancies")
Поиск по вакансиям
GET api.hh.ru/vacancies
параметры: page, per_page, text, search_field, experience, employment, schedule, area и ещё 36
класс доступа: чтение
hh_call_method("hh_get_vacancies", {"page": "...", "per_page": "..."})
Три инструмента вместо 133 функций: агент ищет метод словами,
читает его карточку и вызывает. Запись и необратимое спрашивают подтверждение.
Что обычно просят:
- Выгрузить свои вакансии и отклики за период и свести в таблицу.
- Посмотреть статистику зарплат по роли перед публикацией вакансии.
- Найти вакансии конкурентов по региону и профессиональной роли.
- Ответить кандидатам шаблоном, показав список человеку до отправки.
Безопасность
Сервер работает на машине пользователя, ключи наружу не уходят. У методов три
класса доступа: чтение идёт сразу, запись и необратимые действия требуют
подтверждения. Заголовок авторизации не покидает домены сервиса даже при вызове
произвольного пути.
Проверить установку
Печатает, сколько методов загрузилось, найдены ли ключи и откуда. Секреты не
показывает. С --live делает один дешёвый реальный вызов на чтение.
Родня
Ядро вынесено в schema-mcp-core.
Соседние серверы: vk-mcp-ru, diadoc-mcp-ru, sbis-mcp-ru, chestny-znak-mcp-ru.
Маркетплейсы живут отдельно: marketplaces-mcp-ru.
MIT. Автор Илья Утов.
Все проекты одним списком, разобранные по назначению:
ilyautov.github.io.
Privacy Policy
hh-mcp-ru не собирает и не передаёт ваши данные: ключи лежат локально в
~/.ru-mcp/cabinets.json, запросы идут только в API hh.ru, телеметрии нет.
Полный текст: PRIVACY_POLICY.md.