How do I use @theyahia/hh-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@theyahia/hh-mcp Find senior backend developer jobs in Moscow with salary over 150k" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

@theyahia/hh-mcp

by theYahia

Overview Schema Related Servers Score Discussions

TypeScript

Remote

@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.

npm License: MIT

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.

Related MCP server: laddro-career-mcp

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

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

HeadHunter MCP Server
Search App Automation
gmen1057
A
license
Not graded
quality
D
maintenance
Enables AI assistants to search job vacancies, manage resumes, and apply to jobs on HeadHunter (hh.ru), Russia's largest job search platform. Includes OAuth 2.0 integration for secure job applications and an automated vacancy hunter agent with intelligent matching.
Updated a year ago (2025-10-13 09:49 UTC)
27
MIT
laddro-career-mcpofficial
Workplace & Productivity Content Management Systems AI & Machine Learning
laddro-app
A
license
A
quality
A
maintenance
Resume tailoring, cover letter generation, CV PDF export, and job search tools for AI agents. 18 tools powered by the Laddro Career API.
Updated 25 days ago (2026-08-07 07:55 UTC)
18
117
MIT
HuntFlow MCP Server
CRM Search
theYahia
A
license
B
quality
C
maintenance
Integrates with HuntFlow ATS to manage vacancies, candidates, resumes, and recruitment stages via 7 tools and 2 skill prompts.
Updated 2 months ago (2026-06-23 12:47 UTC)
7
50
1
MIT
HeadHunter API MCP Server
CRM Search
sargonpiraev
A
license
Not graded
quality
F
maintenance
Enables AI assistants to access and manage HeadHunter job platform data, including vacancies, resumes, negotiations, and employer settings via 167+ tools.
Updated 23 days ago (2026-08-08 17:14 UTC)
85
5
MIT

View all related MCP servers

Related MCP Connectors

YouTube Transcript & Search MCP Server
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Human Pages
Hire real humans for tasks agents can't do alone. 36 tools for the full hiring lifecycle.
Sugra API
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/theYahia/hh-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

@theyahia/hh-mcp

Two Modes

Installation

Claude Desktop

Claude Code

VS Code / Cursor

Windsurf

HTTP Mode (Streamable HTTP)

Environment Variables

Tools (19)

Vacancies

Resumes (employer token + paid resume DB)

Employers

Dictionaries & Suggests

Salary & Account

Rate Limiting

Demo Prompts

Development

API Reference

License

Maintenance

Resources

Looking for Admin?

Tools

Related MCP Servers

HeadHunter MCP Server

laddro-career-mcpofficial

HuntFlow MCP Server

HeadHunter API MCP Server

Related MCP Connectors

Latest Blog Posts

MCP directory API