HH MCP Server

HH MCP Server

MCP-сервер для автоматизации работы с hh.ru через браузерную автоматизацию (Playwright).

Возможности

• Поиск вакансий — по ключевым словам, городу, зарплате, опыту, графику (удалёнка/офис/гибрид)
• Просмотр деталей вакансий — полное описание, требования, стек, условия
• Управление резюме — просмотр списка и содержимого своих резюме
• Отклики на вакансии — с сопроводительным письмом и ответами на вопросы работодателя
• Отслеживание откликов — статусы всех отправленных откликов
• Информация о работодателях — карточка компании

Требования

• Python 3.12+
• uv (менеджер пакетов)

Установка

cd hh-mcp-server
uv sync
uv run playwright install chromium

Авторизация

Перед первым использованием нужно авторизоваться на hh.ru:

uv run hh-mcp-server --login

Откроется браузер — войдите в свой аккаунт hh.ru. Сессия сохранится в ~/.hh-mcp/profile/state.json.

Запуск

Как MCP-сервер (stdio, для Claude Code)

uv run hh-mcp-server

С видимым браузером (для отладки)

uv run hh-mcp-server --no-headless

HTTP-транспорт

uv run hh-mcp-server --transport streamable-http --port 8766

Настройка в Claude Code

Добавьте в .claude/settings.json:

{
  "mcpServers": {
    "hh": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/hh-mcp-server", "hh-mcp-server"]
    }
  }
}

MCP-инструменты

| Инструмент | Описание | |---|---| | search_vacancies | Поиск вакансий по ключевым словам (keywords, area, salary, experience, schedule) | | get_recommended_vacancies | Подходящие вакансии для резюме (алгоритм hh.ru, до 1000 вакансий) | | get_vacancy_details | Детали вакансии по ID | | get_my_resumes | Список резюме пользователя | | get_resume | Полное содержимое резюме | | apply_to_vacancy | Отклик на вакансию (с письмом и ответами на вопросы) | | get_responses | Статусы откликов | | get_employer_info | Информация о компании | | close_session | Закрытие браузера и сохранение сессии |

Рекомендованные вакансии

Инструмент get_recommended_vacancies использует алгоритм hh.ru для подбора вакансий на основе резюме (аналог страницы "Подходящие вакансии"):

get_recommended_vacancies(
    resume_id="0fe69243ff063cb4720039ed1f574b71676a55",
    max_pages=50  # до 1000 вакансий (20 на страницу)
)

Это значительно точнее, чем keyword search — hh.ru анализирует опыт, навыки и должность из резюме.

Отклик на вакансию (двухшаговый flow)

Некоторые вакансии имеют обязательные вопросы от работодателя:

1. Первый вызов без question_answers — возвращает список вопросов
2. Второй вызов с question_answers — отправляет отклик

# Шаг 1: получить вопросы
apply_to_vacancy(vacancy_id="12345")
# → {"status": "questions_required", "questions": [...]}

# Шаг 2: отправить с ответами
apply_to_vacancy(
    vacancy_id="12345",
    resume_id="abc123",
    cover_letter="Текст письма",
    question_answers={"task_123_text": "Ответ на вопрос"}
)

Структура проекта

hh_mcp_server/
├── cli_main.py       # CLI точка входа (--login, --no-headless, --transport)
├── server.py         # FastMCP сервер, регистрация инструментов
├── constants.py      # URL, пути, маппинги (города, графики, опыт)
├── exceptions.py     # Кастомные исключения
├── drivers/
│   └── browser.py    # Playwright: контекст, страница, сохранение сессии
├── tools/
│   ├── vacancy.py    # Инструменты поиска и просмотра вакансий
│   ├── apply.py      # Инструмент отклика на вакансию
│   ├── resume.py     # Инструменты работы с резюме
│   ├── employer.py   # Информация о работодателе
│   └── responses.py  # Отслеживание откликов
├── scraping/
│   ├── selectors.py  # CSS-селекторы для парсинга hh.ru
│   ├── extractor.py  # Утилиты извлечения данных со страниц
│   ├── apply.py      # Логика отклика (cookies, вопросы, письмо, submit)
│   └── resume.py     # Парсинг страниц резюме
└── utils/
    └── auth.py       # Авторизация (login flow, проверка сессии)

Логирование

uv run hh-mcp-server --log-level DEBUG

Уровни: DEBUG, INFO, WARNING (по умолчанию), ERROR.