English Français العربية

io.github.theYahia/hh-mcp

السجل الرسمي البحث والويب

MCP server for hh.ru jobs API — vacancy search, salary stats, employers, regions. Public endpoints,

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package @theyahia/hh-mcp
Claude Code 
claude mcp add hh-mcp -e 'API_KEY=<your api_key>' -- npx -y @theyahia/hh-mcp@1.0.0
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "hh-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@theyahia/hh-mcp@1.0.0"
            ],
            "env": {
                "API_KEY": "<your api_key>"
            }
        }
    }
}

متغيرات البيئة

  • API_KEY إلزامي سري API key for the service

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. MCP-сервер для hh.ru API — 19 инструментов для ИИ-агента: вакансии, резюме, зарплаты
  2. Два режима
  3. Установка
  4. Переменные окружения
  5. Инструменты (19)
  6. Ограничение частоты запросов
  7. Демо-промпты
  8. Разработка
  9. Справочник API
  10. Лицензия

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

الأسئلة الشائعة

ما هو io.github.theYahia/hh-mcp؟

MCP server for hh.ru jobs API — vacancy search, salary stats, employers, regions. Public endpoints,

كيف أثبّت io.github.theYahia/hh-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add hh-mcp -e 'API_KEY=<your api_key>' -- npx -y @theyahia/hh-mcp@1.0.0. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.theYahia/hh-mcp إلى مفتاح API؟

نعم. يتطلب API_KEY، وتضبطها في إعداداته.

هل io.github.theYahia/hh-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.theYahia/hh-mcp؟

ينشره theYahia. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.