Skip to main content
Glama
@theyahia/hh-mcp

@theyahia/hh-mcp

by theYahia

@theyahia/hh-mcp

Servidor MCP para la API de hh.ru — el mercado laboral de Rusia y la CEI. 19 herramientas que cubren vacantes, currículums, empleadores, estadísticas salariales, diccionarios, autocompletado y diagnóstico de tokens.

Las respuestas se devuelven como resúmenes compactos y aptos para LLM de forma predeterminada: pasa raw: true a cualquier herramienta de búsqueda/detalle para obtener el JSON completo de hh.ru.

npm CI License: MIT

Parte de la serie Russian API MCP de @theYahia.

Dos modos

Modo

Qué está disponible

¿Token necesario?

Sin token

Búsqueda de vacantes, vacante por ID, vacantes similares, empleadores, estadísticas salariales, áreas, roles, industrias, metro, diccionarios, sugerencias, verificación de token

No

Con token

Todo lo anterior + búsqueda de currículums, currículum por ID

Sí (HH_ACCESS_TOKEN)

Obtén un token en dev.hh.ru/admin. Nota: la búsqueda de currículums además requiere una cuenta de empleador con una suscripción de pago a la base de datos de currículums — los tokens de solicitante/anónimos reciben un 403. Usa validate_token para comprobar qué puede hacer tu token.

Related MCP server: HeadHunter API MCP Server

Instalación

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
# With token:
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"]
    }
  }
}

Modo HTTP (Streamable HTTP)

npx @theyahia/hh-mcp --http
# or
HTTP_PORT=8080 npx @theyahia/hh-mcp --http

Endpoint: http://localhost:3000/mcp (POST) · Comprobación de salud: http://localhost:3000/health (GET)

El modo HTTP es sin estado y se vincula a 127.0.0.1 de forma predeterminada con protección contra reenlace de DNS activada. Para exponerlo, establece HOST=0.0.0.0 y añade tu host/origen a HH_ALLOWED_HOSTS / HH_ALLOWED_ORIGINS, y colócalo detrás de tu propia autenticación.

Variables de entorno

Variable

¿Requerida?

Descripción

HH_ACCESS_TOKEN

No

Token Bearer OAuth 2.0. Requerido para los endpoints de currículums (empleador + base de datos de pago).

HH_USER_AGENT

No

HH-User-Agent personalizado (hh.ru lo requiere). Se recomienda tu-app/1.0 (tu@ejemplo.com).

HTTP_PORT / PORT

No

Puerto para el modo HTTP (predeterminado: 3000).

HOST

No

Interfaz a la que vincularse en el modo HTTP (predeterminado: 127.0.0.1).

HH_ALLOWED_HOSTS

No

Lista de Hosts permitidos separados por comas para el modo HTTP (predeterminado: loopback).

HH_ALLOWED_ORIGINS

No

Lista de Orígenes permitidos separados por comas para el modo HTTP.

Consulta .env.example.

Herramientas (19)

Cada herramienta de búsqueda/detalle acepta raw: true para devolver el JSON completo de hh.ru en lugar del resumen compacto.

Vacantes

Herramienta

Descripción

¿Token?

search_vacancies

Busca por palabras clave, región, rol profesional, industria, metro, empleador, salario, experiencia, formato de trabajo / tipo de empleo, rango de fechas (period o date_from/date_to), etiquetas, campo de búsqueda, con ordenación y paginación

No

get_vacancy

Detalles completos de la vacante: descripción, requisitos, habilidades clave, contactos

No

get_similar_vacancies

Encuentra vacantes similares a una dada

No

Currículums (token de empleador + base de datos de currículums de pago)

Herramienta

Descripción

¿Token?

search_resumes

Busca currículums de candidatos por palabras clave, región, rol, salario, experiencia

Sí

get_resume

Currículum completo: experiencia, educación, habilidades, contactos

Sí

Empleadores

Herramienta

Descripción

¿Token?

search_employers

Busca empresas por nombre y región

No

get_employer

Perfil del empleador: descripción, industrias, sitio web, número de vacantes

No

get_employer_vacancies

Lista las vacantes activas de un empleador específico

No

Diccionarios y sugerencias

Herramienta

Descripción

¿Token?

get_areas

Árbol de regiones y ciudades (id — nombre)

No

get_areas_subtree

Regiones/ciudades bajo un id de área — más ligero que el árbol completo

No

get_professional_roles

Árbol de roles profesionales con IDs

No

get_industries

Árbol de industrias de empresas con IDs

No

get_metro

Estaciones/líneas de metro con IDs para una ciudad

No

get_dictionaries

Todos los datos de referencia: monedas, tipos de empleo, horarios, experiencia, etiquetas

No

suggest_positions

Autocompletar títulos de puestos

No

suggest_companies

Autocompletar nombres de empresas

No

suggest_areas

Autocompletar nombres de regiones/ciudades

No

Salario y cuenta

Herramienta

Descripción

¿Token?

get_salary_statistics

Distribución salarial estimada (mediana, P25/P75, mín/máx) para un rol en una región, calculada a partir de los salarios de vacantes publicadas. Muestra sesgada, no son datos oficiales del mercado.

No

validate_token

Comprueba si HH_ACCESS_TOKEN es válido (a través de /me) e informa del rol de la cuenta

No

Limitación de velocidad

El limitador de velocidad integrado respeta el límite de la API de hh.ru de 5 solicitudes por segundo. Reintento automático con retroceso exponencial en errores 429 y 5xx (hasta 3 intentos). Nota: el limitador es global al proceso, por lo que en el modo HTTP compartido todos los clientes comparten un presupuesto de 5 req/s.

Prompts de demostración

Find remote Python developer jobs in Moscow paying over 300,000 RUB
Show me all open vacancies at Yandex and give me salary statistics for their top roles
Compare Senior Backend salaries in Moscow vs Saint Petersburg, and suggest similar vacancies to the best-paying one

Desarrollo

git clone https://github.com/theYahia/hh-mcp.git
cd hh-mcp
npm install
npm run build
npm test

Referencia de la API

Licencia

MIT

Available Tools

19 tools
get_areasA

Get the full tree of regions and cities as id — name lines (pass raw:true for nested JSON). Use to find area IDs for search filters.

Inputs: raw.

get_areas_subtreeA

Get the regions/cities subtree under one area id (e.g. 113=Russia) — lighter than the full /areas tree.

Inputs: area_id (required), raw.

get_dictionariesA

Get all reference dictionaries: currencies, employment types, schedules, experience levels, vacancy labels, and more.

Inputs: no named parameters.

get_employerA

Get detailed employer profile: description, industries, website, vacancy count.

Inputs: employer_id (required), raw.

get_employer_vacanciesC

List active vacancies for a specific employer.

Inputs: employer_id (required), raw, page, per_page.

get_industriesA

Get the tree of company industries with IDs. Use to find industry IDs for the search_vacancies industry filter.

Inputs: raw.

get_metroA

Get metro stations and lines with IDs for a city (city_id), or for all cities. Use to find metro IDs for the search_vacancies metro filter.

Inputs: city_id.

get_professional_rolesA

Get the tree of professional roles with IDs. Use to find role IDs for vacancy/resume search and salary stats.

Inputs: raw.

get_resumeA

Get full resume details: experience, education, skills, contacts. Requires an EMPLOYER OAuth token + paid resume-database access.

Inputs: resume_id (required), raw.

get_salary_statisticsA

Estimate salary distribution (median, P25/P75, min/max) for a professional role in a region by sampling posted vacancy salaries client-side. Biased sample (only vacancies that disclose salary) — not official market data.

Inputs: professional_role_id (required), raw, text, area_id, +1 more.

get_similar_vacanciesB

Find vacancies similar to a given one. Useful for expanding a candidate's job search.

Inputs: vacancy_id (required), raw, page, per_page.

get_vacancyB

Get full vacancy details: description, requirements, key skills, contacts, employer info.

Inputs: vacancy_id (required), raw.

search_employersA

Search companies/employers on hh.ru by name. Returns company info and open vacancy count.

Inputs: text (required), raw, area, page, +1 more.

search_resumesA

Search candidate resumes by keywords, region, professional role, salary, experience. Requires an EMPLOYER OAuth token (HH_ACCESS_TOKEN) AND a paid hh.ru resume-database subscription — applicant/anonymous tokens get 403.

Inputs: raw, area, page, text, +4 more.

search_vacanciesA

Search job vacancies on hh.ru by keywords, region, professional role, industry, metro, salary, experience, employment form, work format, date range and labels. Returns a compact paginated summary (pass raw:true for full JSON).

Inputs: raw, area, page, text, +19 more.

suggest_areasA

Autocomplete region/city names. Returns matching area suggestions for partial input.

Inputs: text (required), raw.

suggest_companiesB

Autocomplete company names. Returns matching employer suggestions for partial input.

Inputs: text (required), raw.

suggest_positionsA

Autocomplete job titles / professional roles. Returns matching role suggestions for partial input.

Inputs: text (required), raw.

validate_tokenA

Check whether HH_ACCESS_TOKEN is valid via /me and report the user role (applicant/employer). Use to diagnose resume-search access.

Inputs: raw.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: search/get for vacancies, resumes, employers, plus reference data and suggestions. Even similar tools like get_areas vs get_areas_subtree have clearly separated purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (search_vacancies, get_vacancy, suggest_areas). No mixing of conventions or vague verbs.

    Tool Count4/5

    19 tools is on the higher end but well-justified for a comprehensive job API covering search, retrieval, suggestions, and reference data. Not excessive enough to be a problem.

    Completeness5/5

    The tool surface covers all major read-only operations for hh.ru: vacancy/resume/employer search and retrieval, similar vacancies, salary stats, and reference dictionaries. No obvious gaps for the intended purpose.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to search job vacancies, manage resumes, and apply to jobs on HeadHunter (hh.ru), Russia's largest job search platform. Includes OAuth 2.0 integration for secure job applications and an automated vacancy hunter agent with intelligent matching.
      38
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI assistants to access and manage HeadHunter job platform data, including vacancies, resumes, negotiations, and employer settings via 167+ tools.
      5
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables to interact with hh.ru (a Russian job platform) through browser automation, allowing users to search for jobs, manage resumes, apply to vacancies with cover letters, and track application statuses via natural language.
      9
      3
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables LLM agents to query and analyze hh.ru job vacancies via full-text and semantic search, with tools for vacancy lookup, skill statistics, market overview, and candidate profile comparison.
      7
      MIT