io.github.theYahia/hh-mcp
MCP server for hh.ru jobs API β vacancy search, salary stats, employers, regions. Public endpoints,
Ask AI about io.github.theYahia/hh-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.theYahia/hh-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
@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
License
MIT
