About io.github.theYahia/hh-mcp
io.github.theYahia/hh-mcp is an MCP server in the Search category: mCP server for hh.ru jobs API — vacancy search, salary stats, employers, regions. Public endpoints,.
Install
claude mcp add io-github-theyahia-hh-mcp -- npx -y @theyahia/hh-mcpnpx -y @theyahia/hh-mcpThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Ask AI
Ask AI about io.github.theYahia/hh-mcp
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
@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
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.