hh-ru MCP server

MCP-сервер для поиска вакансий в России и на удалёнке прямо из AI-ассистента (Claude Desktop, Cursor, Claude Code и других MCP-клиентов).

Под капотом — официальные и открытые API нескольких площадок, собранные в один набор инструментов:

Площадка	Ключ нужен?	Что даёт
hh.ru	опционально (OAuth)	основной поиск вакансий по РФ
Работа России (trudvsem)	нет	государственный портал вакансий
SuperJob	да (SUPERJOB_APP_KEY)	вакансии SuperJob
Remotive / RemoteOK / Jobicy	нет	зарубежная IT-удалёнка

Сервер написан на FastMCP, работает по транспорту stdio и обращается к API через curl_cffi с имитацией браузера (chrome120), чтобы обходить базовую анти-бот защиту.

Инструменты

Инструмент	Площадка	Описание
search_vacancies	hh.ru	поиск вакансий с фильтрами (регион, зарплата, опыт, формат работы, сортировка)
get_vacancy	hh.ru	полное описание вакансии по id
find_area_id	hh.ru	поиск id региона/города для фильтра area
search_trudvsem	Работа России	поиск вакансий, фильтр по региону и зарплате
find_superjob_town	SuperJob	поиск id города для фильтра town
search_superjob	SuperJob	поиск вакансий (нужен ключ приложения)
search_remote_jobs	Remotive/RemoteOK/Jobicy	агрегатор зарубежной удалёнки (англоязычные запросы)

Требования

• Python 3.12+
• Зависимости из requirements.txt: mcp, curl_cffi

Установка

git clone <repo-url>
cd MCP

python -m venv .venv
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Linux / macOS:
source .venv/bin/activate

pip install -r requirements.txt

Настройка

Все переменные окружения опциональны — сервер запустится и без них, но с ограничениями. Список — в .env.example:

Переменная	Назначение
HH_TOKEN	OAuth-токен hh.ru. Рекомендуется: без него поиск может возвращать 403, если IP попал в чёрный список. Получить на dev.hh.ru.
HH_CLIENT_ID, HH_CLIENT_SECRET	Альтернатива HH_TOKEN — токен получается автоматически по client_credentials.
HH_PROXY	Прокси для запросов к hh.ru (http://user:pass@host:port).
SUPERJOB_APP_KEY	Secret key приложения SuperJob. Нужен только для search_superjob и find_superjob_town. Получить на api.superjob.ru.

Подключение к MCP-клиенту

Скопируйте .mcp.json.example в .mcp.json (или добавьте запись в конфиг вашего клиента) и пропишите ключи и путь к Python из вашего виртуального окружения:

{
  "mcpServers": {
    "hh-ru": {
      "command": "/абсолютный/путь/.venv/bin/python",
      "args": ["/абсолютный/путь/server.py"],
      "env": {
        "HH_TOKEN": "ваш_токен",
        "SUPERJOB_APP_KEY": "ваш_ключ"
      }
    }
  }
}

Пример конфига также включает сервер playwright — он не обязателен для поиска, но удобен, если AI-ассистент должен ещё и открывать страницы вакансий в браузере.

Запуск

Обычно сервер запускает сам MCP-клиент по конфигу выше. Для ручной проверки:

python server.py

Сервер общается по stdio (ждёт MCP-протокол на stdin/stdout) — это нормально, что в терминале нет вывода.

Примечания

• hh.ru и 403. Поисковый API hh.ru может банить IP. Если видите ошибку про чёрный список — задайте HH_TOKEN, используйте HH_PROXY или смените сеть (например, мобильный интернет).
• Зарубежная удалёнка. search_remote_jobs возвращает в основном вакансии, где компании не нанимают резидентов РФ. Проверяйте поле location и требования по юрисдикции/релокации.
• Безопасность. Не коммитьте реальные ключи. .env и .mcp.json добавлены в .gitignore; для публикации используйте *.example-шаблоны.

Структура

.
├── server.py            # MCP-сервер и все инструменты
├── requirements.txt     # зависимости
├── .env.example         # шаблон переменных окружения
├── .mcp.json.example    # шаблон конфига MCP-клиента
└── .gitignore