Back to Browse
Free
Server data from the Official MCP Registry
MCP server for hh.ru jobs API — vacancy search, salary stats, employers, regions. Public endpoints,
About
MCP server for hh.ru jobs API — vacancy search, salary stats, employers, regions. Public endpoints,
Security Report
5.0
Moderate5.0Moderate RiskValid MCP server (2 strong, 4 medium validity signals). 4 known CVEs in dependencies (1 critical, 3 high severity) Package registry verified. Imported from the Official MCP Registry.
12 files analyzed · 5 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
API key for the serviceRequired
Environment variable: API_KEY
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-theyahia-hh-mcp": {
"env": {
"API_KEY": "your-api-key-here"
},
"args": [
"-y",
"@theyahia/hh-mcp"
],
"command": "npx"
}
}
}Documentation
View on GitHubFrom the project's GitHub README.
@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 (you@example.com). |
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
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Fetch
Freeby Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
80.0K
Stars
5
Installs
5.3
Security
No ratings yet
Local
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
80.0K
Stars
6
Installs
6.5
Security
No ratings yet
Local
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
137
Stars
531
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
77
Installs
10.0
Security
4.6
Local
MarkItDown
Freeby Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
156.1K
Stars
42
Installs
6.0
Security
5.0
Local
FinAgent
Freeby mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
-
Stars
24
Installs
10.0
Security
No ratings yet
Local