@theyahia/hh-mcp

MCP server for the hh.ru API — Russia and CIS job market. 19 tools covering vacancies, resumes, employers, salary statistics, dictionaries, autocomplete, and token diagnostics.

Responses are returned as compact, LLM-friendly summaries by default — pass raw: true to any search/detail tool to get the full hh.ru JSON.

Part of the Russian API MCP series by @theYahia.

Two Modes

| Mode | What's available | Token needed? | |------|-----------------|:-------------:| | No token | Vacancy search, vacancy by ID, similar vacancies, employers, salary stats, areas, roles, industries, metro, dictionaries, suggests, token check | No | | With token | Everything above + resume search, resume by ID | Yes (HH_ACCESS_TOKEN) |

Get a token at dev.hh.ru/admin. Note: resume search additionally requires an employer account with a paid resume-database subscription — applicant/anonymous tokens get a 403. Use validate_token to check what your token can do.

Installation

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"]
    }
  }
}

HTTP Mode (Streamable HTTP)

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

Endpoint: http://localhost:3000/mcp (POST) · Health check: http://localhost:3000/health (GET)

HTTP mode is stateless and binds to 127.0.0.1 by default with DNS-rebinding protection on. To expose it, set HOST=0.0.0.0 and add your host/origin to HH_ALLOWED_HOSTS / HH_ALLOWED_ORIGINS, and put it behind your own auth.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | HH_ACCESS_TOKEN | No | OAuth 2.0 Bearer token. Required for resume endpoints (employer + paid resume DB). | | HH_USER_AGENT | No | Custom HH-User-Agent (hh.ru requires it). Recommend your-app/1.0 ([email protected]). | | HTTP_PORT / PORT | No | Port for HTTP mode (default: 3000). | | HOST | No | Interface to bind in HTTP mode (default: 127.0.0.1). | | HH_ALLOWED_HOSTS | No | Comma-separated Host allow-list for HTTP mode (default: loopback). | | HH_ALLOWED_ORIGINS | No | Comma-separated Origin allow-list for HTTP mode. |

See .env.example.

Tools (19)

Every search/detail tool accepts raw: true to return the full hh.ru JSON instead of the compact summary.

Vacancies

| Tool | Description | Token? | |------|-------------|:------:| | search_vacancies | Search by keywords, region, professional role, industry, metro, employer, salary, experience, work format / employment form, date range (period or date_from/date_to), labels, search field, with sorting and pagination | No | | get_vacancy | Full vacancy details: description, requirements, key skills, contacts | No | | get_similar_vacancies | Find vacancies similar to a given one | No |

Resumes (employer token + paid resume DB)

| Tool | Description | Token? | |------|-------------|:------:| | search_resumes | Search candidate resumes by keywords, region, role, salary, experience | Yes | | get_resume | Full resume: experience, education, skills, contacts | Yes |

Employers

| Tool | Description | Token? | |------|-------------|:------:| | search_employers | Search companies by name and region | No | | get_employer | Employer profile: description, industries, website, vacancy count | No | | get_employer_vacancies | List active vacancies for a specific employer | No |

Dictionaries & Suggests

| Tool | Description | Token? | |------|-------------|:------:| | get_areas | Tree of regions and cities (id — name) | No | | get_areas_subtree | Regions/cities under one area id — lighter than the full tree | No | | get_professional_roles | Tree of professional roles with IDs | No | | get_industries | Tree of company industries with IDs | No | | get_metro | Metro stations/lines with IDs for a city | No | | get_dictionaries | All reference data: currencies, employment types, schedules, experience, labels | No | | suggest_positions | Autocomplete job titles | No | | suggest_companies | Autocomplete company names | No | | suggest_areas | Autocomplete region/city names | No |

Salary & Account

| Tool | Description | Token? | |------|-------------|:------:| | get_salary_statistics | Estimated salary distribution (median, P25/P75, min/max) for a role in a region, computed from posted vacancy salaries. Biased sample, not official market data. | No | | validate_token | Check whether HH_ACCESS_TOKEN is valid (via /me) and report the account role | No |

Rate Limiting

Built-in rate limiter respects the hh.ru API limit of 5 requests per second. Automatic retry with exponential backoff on 429 and 5xx errors (up to 3 attempts). Note: the limiter is process-global, so in shared HTTP mode all clients share one 5 req/s budget.

Demo Prompts

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

Development

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

API Reference

• hh.ru API docs
• hh.ru API GitHub

License

MIT