@theyahia/hh-mcp

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

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, dictionaries, suggests	No
With token	Everything above + resume search, resume by ID	Yes (HH_ACCESS_TOKEN)

Get a token at dev.hh.ru/admin.

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 Health check: http://localhost:3000/health

Environment Variables

Variable	Required	Description
HH_ACCESS_TOKEN	No	OAuth 2.0 Bearer token. Required for resume endpoints.
HTTP_PORT	No	Port for HTTP mode (default: 3000).

Tools (16)

Vacancies

Tool	Description	Token?
search_vacancies	Search vacancies by keywords, region, salary, experience, employment type, schedule, 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

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	Full tree of regions and cities with codes	No
get_professional_roles	Full tree of professional roles with IDs	No
get_dictionaries	All reference data: currencies, employment types, schedules, experience levels	No
suggest_positions	Autocomplete job titles	No
suggest_companies	Autocomplete company names	No
suggest_areas	Autocomplete region/city names	No

Salary

Tool	Description	Token?
get_salary_statistics	Salary distribution for a professional role in a region	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

... View full README on GitHub