hh-ru MCP server

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

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

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

Инструменты

Related MCP server: HeadHunter API MCP Server

Требования

• 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:

Подключение к 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