@theyahia/hh-mcp
@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.
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í ( |
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-mcpVS 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 --httpEndpoint: 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 |
| No | Token Bearer OAuth 2.0. Requerido para los endpoints de currículums (empleador + base de datos de pago). |
| No |
|
| No | Puerto para el modo HTTP (predeterminado: 3000). |
| No | Interfaz a la que vincularse en el modo HTTP (predeterminado: |
| No | Lista de Hosts permitidos separados por comas para el modo HTTP (predeterminado: loopback). |
| 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? |
| Busca por palabras clave, región, rol profesional, industria, metro, empleador, salario, experiencia, formato de trabajo / tipo de empleo, rango de fechas ( | No |
| Detalles completos de la vacante: descripción, requisitos, habilidades clave, contactos | No |
| Encuentra vacantes similares a una dada | No |
Currículums (token de empleador + base de datos de currículums de pago)
Herramienta | Descripción | ¿Token? |
| Busca currículums de candidatos por palabras clave, región, rol, salario, experiencia | Sí |
| Currículum completo: experiencia, educación, habilidades, contactos | Sí |
Empleadores
Herramienta | Descripción | ¿Token? |
| Busca empresas por nombre y región | No |
| Perfil del empleador: descripción, industrias, sitio web, número de vacantes | No |
| Lista las vacantes activas de un empleador específico | No |
Diccionarios y sugerencias
Herramienta | Descripción | ¿Token? |
| Árbol de regiones y ciudades ( | No |
| Regiones/ciudades bajo un id de área — más ligero que el árbol completo | No |
| Árbol de roles profesionales con IDs | No |
| Árbol de industrias de empresas con IDs | No |
| Estaciones/líneas de metro con IDs para una ciudad | No |
| Todos los datos de referencia: monedas, tipos de empleo, horarios, experiencia, etiquetas | No |
| Autocompletar títulos de puestos | No |
| Autocompletar nombres de empresas | No |
| Autocompletar nombres de regiones/ciudades | No |
Salario y cuenta
Herramienta | Descripción | ¿Token? |
| 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 |
| Comprueba si | 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 RUBShow me all open vacancies at Yandex and give me salary statistics for their top rolesCompare Senior Backend salaries in Moscow vs Saint Petersburg, and suggest similar vacancies to the best-paying oneDesarrollo
git clone https://github.com/theYahia/hh-mcp.git
cd hh-mcp
npm install
npm run build
npm testReferencia de la API
Licencia
MIT
Available Tools
19 toolsget_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Search remote jobs, read full postings, and get application links from Claude, Codex, Cursor, and other compatible MCP clients. Tools: search_jobs, get_job, get_filters. Supports cursor pagination and location, category, skill, seniority, employment type, and salary availability filters. Free, read-only Streamable HTTP; no account or API key required. Posting-based facts; remote does not imply worldwide eligibility. Setup: https://heyrole.ai/developers
Job-posting search (jobicy, HN Who is Hiring, arbeitnow) and US H-1B salary data as agent tools.
Salary and H-1B disclosed-wage data as agent tools.
Web scraping and search, geocoding, IP and domain checks, translation, weather. 15 tools, x402.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.38MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to access and manage HeadHunter job platform data, including vacancies, resumes, negotiations, and employer settings via 167+ tools.5MIT
- FlicenseAqualityDmaintenanceEnables 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.93-
- AlicenseAqualityBmaintenanceEnables 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.7MIT