@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

License

MIT

Hh MCP

README