@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 5xx errors (up to 3 attempts).

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