hh-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HOST | No | Interface to bind in HTTP mode (default 127.0.0.1). | |
| PORT | No | Port for HTTP mode (default 3000). Alternative to HTTP_PORT. | |
| HTTP_PORT | No | Port for HTTP mode (default 3000). Alternative to PORT. | |
| HH_USER_AGENT | No | Custom HH-User-Agent (required by hh.ru). Recommended format: your-app/1.0 (you@example.com). | |
| HH_ACCESS_TOKEN | No | Bearer-token OAuth 2.0. Needed for resumes, ATS/response, and employer-scoped endpoints. Optional. | |
| HH_ALLOWED_HOSTS | No | Comma-separated list of allowed Host headers for HTTP mode (default loopback). | |
| HH_ALLOWED_ORIGINS | No | Comma-separated list of allowed Origin headers for HTTP mode. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_vacanciesA | Search job vacancies on hh.ru by keywords, region, professional role, industry, metro, salary, experience, employment form, work format, date range and labels. Returns a compact paginated summary (pass raw:true for full JSON). |
| get_vacancyB | Get full vacancy details: description, requirements, key skills, contacts, employer info. |
| get_similar_vacanciesB | Find vacancies similar to a given one. Useful for expanding a candidate's job search. |
| get_related_vacanciesB | Find vacancies related to a given one (hh.ru related_vacancies endpoint). Public, no token. |
| get_vacancy_statsB | Get employer-facing vacancy statistics (views/responses/invitations). Requires HH_ACCESS_TOKEN. |
| get_vacancy_visitorsB | List visitors who viewed a vacancy. Requires HH_ACCESS_TOKEN. |
| get_vacancy_conditionsB | Get vacancy publication conditions / constraints for the current employer. Requires HH_ACCESS_TOKEN. |
| search_resumesA | Search candidate resumes by keywords, region, professional role, salary, experience. Requires an EMPLOYER OAuth token (HH_ACCESS_TOKEN) AND a paid hh.ru resume-database subscription — applicant/anonymous tokens get 403. |
| get_resumeA | Get full resume details: experience, education, skills, contacts. If the resume came through an отклик, always pass topic_id (+vacancy_id): the unscoped read hits the resume database, consumes a paid view and is the call hh.ru captcha-gates. When HH_REQUIRE_TOPIC is on, unscoped reads require allow_unscoped:true. Requires an EMPLOYER OAuth token + paid resume-database access. |
| get_resume_negotiations_historyB | Get negotiation history for a resume (employer view). Requires HH_ACCESS_TOKEN. |
| list_saved_resume_searchesA | List saved resume searches for the current employer account. Requires HH_ACCESS_TOKEN. |
| get_saved_resume_searchB | Get a saved resume search by id. Requires HH_ACCESS_TOKEN. |
| get_resumesA | Safely fetch up to 50 resumes sequentially through the resume-view budget (default ~1.5s spacing, 20 reads/60s window). Preferred input: items:[{resume_id, topic_id}] + vacancy_id for scoped reads; set require_topic:true to never read the paid database. Legacy resume_ids+topics is validated (typo'd keys fail before any request). Reads without topic_id return status unscoped. Pass out_dir to persist payloads (raw/*.json + manifest.json + negotiations.csv). stop_on_captcha default true. max_wait_ms default 90000 (cap 110000). Requires HH_ACCESS_TOKEN. |
| collect_vacancy_resumesA | Walk a vacancy funnel (collection/sub_collection), fetch each resume with topic_id through the gated budget, write raw JSON + manifest/csv under out_dir (HH_EXPORT_DIR). Bounded by max (default 25) and max_wait_ms; returns an id-based cursor/remaining when truncated (safe when new responses arrive between calls). Prefer this over spawning subagents. Requires HH_ACCESS_TOKEN. |
| list_application_collectionsA | Vacancy application funnel: per-stage and per-sub-stage counters plus unread (with_updates). Sub-collection ids are inputs for list_applications. Also lists employer_states. Start here before list_applications. Requires HH_ACCESS_TOKEN. |
| list_applicationsA | List applications for a vacancy by collection or sub_collection (id/name), with optional with_updates_only (scans collection pages for has_updates; page/per_page are the filtered stream; capped by HH_MAX_SCAN_PAGES), page/per_page/order_by. raw:true returns one unfiltered upstream page. Defaults collection to response. Requires HH_ACCESS_TOKEN. |
| get_applicationA | Full application card from the negotiations endpoint (candidate, relevant experience, funnel stage, message counters) — prefer over get_resume for screening. Requires HH_ACCESS_TOKEN. |
| get_application_messagesA | Paginated chat messages for an application topic (page/per_page, max 50). Requires HH_ACCESS_TOKEN. |
| get_negotiations_statisticsB | Get employer-level negotiations statistics. Requires employer_id and HH_ACCESS_TOKEN. |
| get_preferred_negotiations_orderA | Get the preferred negotiations sort order for a vacancy. Requires HH_ACCESS_TOKEN. |
| search_employersA | Search companies/employers on hh.ru by name. Returns company info and open vacancy count. |
| get_employerA | Get detailed employer profile: description, industries, website, vacancy count. |
| get_employer_vacanciesA | List active vacancies for a specific employer via public vacancy search (employer_id filter). No token required. |
| list_employer_managersA | List managers for an employer account. employer_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN. |
| get_employer_managerA | Get a single employer manager by id. employer_id/manager_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN. |
| get_manager_resume_limitsA | Informational resume-view limits for a manager (hh.ru counter may not match real views; 404/zeros are not a captcha signal). employer_id/manager_id of the authenticated account can be omitted (resolved from /me). Do not pass 0. Requires HH_ACCESS_TOKEN. |
| get_manager_negotiations_statisticsB | Get negotiations statistics for a manager. employer_id/manager_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN. |
| list_active_vacanciesA | List published (active) vacancies for the authenticated employer account via /employers/{id}/vacancies/active. Requires HH_ACCESS_TOKEN. For any employer's public vacancies use get_employer_vacancies. |
| list_archived_vacanciesA | List archived vacancies for an employer. Requires HH_ACCESS_TOKEN. |
| list_hidden_vacanciesB | List hidden vacancies for an employer. Requires HH_ACCESS_TOKEN. |
| get_message_templateB | Get a negotiation message template by id (optionally with topic_id / resume_id / vacancy_id). Requires HH_ACCESS_TOKEN. |
| list_mail_templatesB | List employer mail templates. Requires employer_id and HH_ACCESS_TOKEN. |
| get_employer_vacancy_areasB | List active vacancy areas for an employer. Requires HH_ACCESS_TOKEN. |
| get_employer_departmentsA | List departments for an employer. employer_id of the authenticated account can be omitted (resolved from /me). Requires HH_ACCESS_TOKEN. |
| list_employer_addressesB | List addresses for an employer. Requires HH_ACCESS_TOKEN. |
| get_areasA | Get the full tree of regions and cities as |
| get_areas_subtreeA | Get the regions/cities subtree under one area id (e.g. 113=Russia) — lighter than the full /areas tree. |
| get_countriesA | List countries (id — name) from /areas/countries. |
| get_professional_rolesA | Get the tree of professional roles with IDs. Use to find role IDs for vacancy/resume search and salary stats. |
| get_industriesA | Get the tree of company industries with IDs. Use to find industry IDs for the search_vacancies |
| get_metroA | Get metro stations and lines with IDs for a city (city_id), or for all cities. Use to find metro IDs for the search_vacancies |
| get_languagesB | List languages (id — name) from /languages. |
| get_skillsA | Resolve skill names by id via /skills (1–50 ids). Use suggest_skill_set to discover ids by name first. |
| get_districtsA | List districts (optionally filtered by area_id). Useful for address/area fine-tuning. |
| get_dictionariesA | Get all reference dictionaries: currencies, employment types, schedules, experience levels, vacancy labels, and more. |
| validate_tokenA | Check whether HH_ACCESS_TOKEN is valid via /me and report the user role (applicant/employer). Use to diagnose resume-search and ATS access. |
| suggest_positionsA | Autocomplete free-form job titles / positions via /suggests/positions (not role IDs — use suggest_professional_roles for those). |
| suggest_professional_rolesA | Autocomplete professional roles with IDs via /suggests/professional_roles. Use for vacancy/resume search filters and salary stats. |
| suggest_companiesB | Autocomplete company names. Returns matching employer suggestions for partial input. |
| suggest_areasA | Autocomplete region/city names. Returns matching area suggestions for partial input. |
| suggest_vacancy_search_keywordC | Autocomplete vacancy-search keywords via /suggests/vacancy_search_keyword. |
| suggest_resume_search_keywordA | Autocomplete resume-search keywords via /suggests/resume_search_keyword. |
| suggest_skill_setC | Autocomplete skills via /suggests/skill_set. |
| get_salary_statisticsA | Salary distribution for a role/region. With HH_ACCESS_TOKEN + area_id, tries paid Банк данных зарплат (/salary_statistics/paid/salary_evaluation/{area_id}); on 401/403/404 or without token/area falls back to sampling vacancy salaries (biased). Optional speciality/employee_level/industry/extend_sources for the bank; text maps to position_name. |
| hh_usage_reportA | Local diagnostics: gated-read ledger / JSONL log summary, captcha breaker state, resume budget, cache hit counts. No network. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 55 tools
Descriptions are detailed and often explicitly say when to prefer one tool over another (e.g., get_application vs get_resume). However, several clusters overlap: get_resumes vs collect_vacancy_resumes vs search_resumes vs get_resume, and list_active/archived/hidden vacancies vs get_employer_vacancies vs search_vacancies. An agent can usually disambiguate with the descriptions, but the sheer number increases misselection risk.
Nearly all tools use snake_case with a verb_noun pattern (get_, list_, search_, suggest_, collect_, validate_). hh_usage_report breaks the verb_noun convention, and a few names are compound or plural, but the overall scheme is predictable and readable.
55 tools far exceeds the 3–15 sweet spot and crosses the 50+ 'extreme mismatch' threshold. While the hh.ru domain is broad, the surface is unwieldy and many list/get endpoints could be consolidated (e.g., vacancy statuses, area lookups), making selection and maintenance burdensome.
The server covers extensive read operations: search, dictionaries, resumes, applications, employer data, and negotiations. However, it lacks write/lifecycle tools such as create/update/delete for vacancies or resumes, apply-to-vacancy, send-message, or status-update actions. Core CRUD coverage is missing, though read-only analysis workflows are well served.