noname-mcp-ru
This server exposes the hh.ru (HeadHunter Russia) API to AI assistants as MCP tools, letting an agent search, inspect, and call 133 cataloged endpoints (plus arbitrary raw paths) for jobs, resumes, responses, employers, salary statistics, and more, with safety gates for write/destructive operations and local credential cabinets.
Discover the API: list sections (
hh_list_sections), get all endpoints in a section (hh_get_section), search methods by Russian/English keywords (hh_search_methods), view a business-entity capability map (hh_map), and read full endpoint cards (hh_describe_method).Read data safely: execute any read-only catalog endpoint (
hh_call_method) or arbitrary GET/HEAD/OPTIONS path (hh_get_raw), with auto-pagination to fetch all rows (hh_fetch_all).Write data with confirmation: create/update via catalog (
hh_write_method) or raw POST/PUT/PATCH (hh_write_raw), both requiringconfirm_write=true.Delete/irreversible actions with double confirmation: catalog destructive endpoints (
hh_delete_method) or raw DELETE (hh_delete_raw), requiring bothconfirm_write=trueandi_understand_this_modifies_data=true.Manage credentials/cabinets: check which env keys are present (
hh_check_auth), list/add/switch/remove named credential cabinets (hh_list_cabinets,hh_add_cabinet,hh_use_cabinet,hh_remove_cabinet), and rotate keys (hh_set_key), with warnings when keys would enter the chat transcript.Typical use cases: pull your vacancies and responses into a table, check salary statistics before posting a job, find competitor vacancies by region/role, and reply to candidates with templates after showing the list for approval.
hh-mcp-ru
API hh.ru для ИИ-ассистентов: вакансии, отклики и приглашения, резюме, справочники, статистика зарплат. Каталог из официальной спеки, у каждого метода класс доступа.
Каталог собран из первоисточника (официальная спека api.hh.ru/openapi/specification/public) и лежит в репозитории как
hh_mcp/endpoints.yaml: 133 метода, из них 92 на чтение,
32 на запись и 9 необратимых. Сервер исполняет ровно этот файл,
поэтому таблица ниже не может разойтись с кодом.
Установка
Два пути, выбирайте по тому, есть ли у вас терминал.
Без терминала: файл .mcpb
Скачайте hh-mcp-ru-vX.Y.Z.mcpb со страницы релизов
и откройте двойным щелчком. Claude Desktop поставит сервер сам и спросит ключи
в отдельном окне, в конфиг лезть не придётся. Нужен Python 3.10 или новее:
зависимости сервер доставит себе при первом запуске.
В терминале
uvx hh-mcp-ruClaude Desktop, claude_desktop_config.json:
{
"mcpServers": {
"hh-mcp": {
"command": "uvx",
"args": ["hh-mcp-ru"],
"env": { "HH_TOKEN": "...", "HH_APP_NAME": "..." }
}
}
}Related MCP server: HeadHunter API MCP Server
Ключи
dev.hh.ru → Мои приложения → создать приложение → access token. HH_APP_NAME заполняется обязательно: hh отклоняет запросы без внятного User-Agent, и это первая причина непонятных ошибок 400.
переменная | секрет | что это |
| да | Токен приложения hh.ru (dev.hh.ru → Мои приложения). |
| нет | Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы. |
Ключи можно не держать в окружении: сервер умеет кабинеты и кладёт их в
~/.ru-mcp/cabinets.json с правами 600, вне репозитория.
Карта методов
раздел | методов | чтение | запись | необратимое |
Работодатель и менеджеры | 30 | 23 | 5 | 2 |
Вакансии | 21 | 12 | 7 | 2 |
Общие справочники | 14 | 6 | 7 | 1 |
Подсказки | 11 | 11 | 0 | 0 |
Отклики и приглашения | 10 | 5 | 5 | 0 |
Сохранённые поиски | 6 | 2 | 3 | 1 |
Статистика зарплат | 5 | 5 | 0 | 0 |
Вебхуки | 4 | 1 | 2 | 1 |
Комментарии к соискателю | 4 | 1 | 2 | 1 |
Резюме | 3 | 3 | 0 | 0 |
Звонки | 3 | 3 | 0 | 0 |
Регионы | 3 | 3 | 0 | 0 |
Токены | 2 | 0 | 1 | 1 |
Учебные заведения | 2 | 2 | 0 | 0 |
Локали | 2 | 2 | 0 | 0 |
Метро | 2 | 2 | 0 | 0 |
Текущий пользователь | 1 | 1 | 0 | 0 |
Аккаунты менеджеров | 1 | 1 | 0 | 0 |
Отрасли | 1 | 1 | 0 | 0 |
Словари | 1 | 1 | 0 | 0 |
Профессиональные роли | 1 | 1 | 0 | 0 |
Языки | 1 | 1 | 0 | 0 |
Навыки | 1 | 1 | 0 | 0 |
Clickme | 1 | 1 | 0 | 0 |
Районы | 1 | 1 | 0 | 0 |
Шаблоны сообщений | 1 | 1 | 0 | 0 |
Условия публикации вакансий | 1 | 1 | 0 | 0 |
всего | 133 | 92 | 32 | 9 |
Как это выглядит в чате
Вы: поиск вакансий
hh_search_methods("поиск вакансий")
hh_get_vacancies GET /vacancies чтение
hh_get_vacancies_related_to_vacancy GET /vacancies/{vacancy_id}/related_vacancies чтение
hh_get_vacancies_similar_to_vacancy GET /vacancies/{vacancy_id}/similar_vacancies чтение
hh_describe_method("hh_get_vacancies")
Поиск по вакансиям
GET api.hh.ru/vacancies
параметры: page, per_page, text, search_field, experience, employment, schedule, area и ещё 36
класс доступа: чтение
hh_call_method("hh_get_vacancies", {"page": "...", "per_page": "..."})Три инструмента вместо 133 функций: агент ищет метод словами, читает его карточку и вызывает. Запись и необратимое спрашивают подтверждение.
Что обычно просят:
Выгрузить свои вакансии и отклики за период и свести в таблицу.
Посмотреть статистику зарплат по роли перед публикацией вакансии.
Найти вакансии конкурентов по региону и профессиональной роли.
Ответить кандидатам шаблоном, показав список человеку до отправки.
Безопасность
Сервер работает на машине пользователя, ключи наружу не уходят. У методов три класса доступа: чтение идёт сразу, запись и необратимые действия требуют подтверждения. Заголовок авторизации не покидает домены сервиса даже при вызове произвольного пути.
Проверить установку
uvx hh-mcp-ru doctorПечатает, сколько методов загрузилось, найдены ли ключи и откуда. Секреты не
показывает. С --live делает один дешёвый реальный вызов на чтение.
Родня
Ядро вынесено в schema-mcp-core. Соседние серверы: vk-mcp-ru, diadoc-mcp-ru, sbis-mcp-ru, chestny-znak-mcp-ru. Маркетплейсы живут отдельно: marketplaces-mcp-ru.
MIT. Автор Илья Утов.
Все проекты одним списком, разобранные по назначению: ilyautov.github.io.
Privacy Policy
hh-mcp-ru не собирает и не передаёт ваши данные: ключи лежат локально в
~/.ru-mcp/cabinets.json, запросы идут только в API hh.ru, телеметрии нет.
Полный текст: PRIVACY_POLICY.md.
Available Tools
18 toolshh_add_cabinetAIdempotent
Add or update a cabinet (a named set of API credentials), from chat.
⚠️ This puts the key into the chat transcript — requires i_understand_key_goes_to_chat=true. The terminal-free safe alternative is the installer (install.py / double-click), where the key never enters chat.
Args: credentials: dict with the required fields for this service ({fields}). For Ozon: {{"client_id": "...", "api_key": "..."}}; for WB: {{"token": "..."}}. name: optional label. If omitted, the cabinet is named after the real shop name fetched from the marketplace (falls back to "main"). i_understand_key_goes_to_chat: must be true to proceed. Saved to ~/.marketplace-mcp/cabinets.json (local, chmod 600), never echoed.
Inputs: credentials (required), name, i_understand_key_goes_to_chat. Returns: result
hh_call_methodARead-only
Execute one READ endpoint from the catalog by operation_id.
Target API: https://api.hh.ru/openapi/specification/public.
Reads only: nothing here changes data, so it runs without confirmation. To change data use hh_write_method, to delete use hh_delete_method.
Args: operation_id: id from the catalog (see hh_search_methods). path_values: values for {placeholders} in the path. query: query-string parameters. body: JSON request body (a few read endpoints take one). Returns JSON: {"ok": true, "status", "data"} or the error envelope.
Inputs: operation_id (required), body, query, path_values. Returns: result
hh_check_authARead-only
Check whether the required credentials are present in the environment.
Does NOT reveal secret values — only reports which variables are set. Returns JSON: {"ready": bool, "missing": [str], "required": [str]}.
Inputs: no named parameters. Returns: result
hh_delete_methodADestructive
Execute one DESTRUCTIVE endpoint: deletes or irreversibly changes data.
Target API: https://api.hh.ru/openapi/specification/public.
Both confirm_write=true and i_understand_this_modifies_data=true are required; nothing is sent without both.
Args: operation_id: id from the catalog (see hh_search_methods). path_values: values for {placeholders} in the path. query: query-string parameters. body: JSON request body. confirm_write: must be true. i_understand_this_modifies_data: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.
Inputs: operation_id (required), body, query, path_values, +2 more. Returns: result
hh_delete_rawADestructive
Delete data at ANY path, including paths not in the catalog.
Target API: https://api.hh.ru/openapi/specification/public.
DELETE only. Both confirm_write=true and i_understand_this_modifies_data=true are required.
Args: path: full path beginning with '/'. method: DELETE. host: host override; defaults to the service's default host. query: query-string parameters. body: JSON request body. confirm_write: must be true. i_understand_this_modifies_data: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.
Inputs: path (required), body, host, query, +3 more. Returns: result
hh_describe_methodBRead-only
Return the full catalog record for one endpoint: method, host, path, scope, safety level, pagination style, rate limit, params and doc URL.
Inputs: operation_id (required). Returns: result
hh_fetch_allARead-only
Auto-paginate a read endpoint and return every row in one response.
Handles offset, last_id, cursor (Ozon v4/v5), page and WB lastChangeDate styles. The array path is taken from the catalog automatically.
Args: operation_id: a read endpoint from the catalog. query / body / path_values: base parameters (cursor fields are managed). items_path: override the array path (default: the endpoint's own). limit: page size to request. max_items: hard cap to protect context (default 10000). Returns JSON: {"ok", "items", "total_fetched", "pages_fetched", "truncated"}.
Inputs: operation_id (required), body, limit, query, +3 more. Returns: result
hh_get_rawARead-only
Read ANY endpoint by path, including ones missing from the catalog.
Target API: https://api.hh.ru/openapi/specification/public.
Safe verbs only (GET, HEAD, OPTIONS). To change data use hh_write_raw, to delete use hh_delete_raw.
Args: path: full path beginning with '/', e.g. "/me". method: safe verb, GET by default. host: host override; defaults to the service's default host. query: query-string parameters. body: JSON request body (rare on reads; some APIs want one). Returns JSON: {"ok": true, "status", "data"} or the error envelope.
Inputs: path (required), body, host, query, +1 more. Returns: result
hh_get_sectionARead-only
List all endpoints in one section.
Args: section: section name (see hh_list_sections), e.g. "statistics". Returns JSON list of {operation_id, method, path, safety, summary}.
Inputs: section (required). Returns: result
hh_list_cabinetsARead-only
List configured cabinets for this marketplace and which one is active.
Returns JSON: {"active": str|null, "cabinets": [names], "fields_needed": [...]}. Secret values are never returned.
Inputs: no named parameters. Returns: result
hh_list_sectionsARead-only
List API sections and how many catalog endpoints each contains.
Inputs: no named parameters. Returns: result
hh_mapARead-only
The big picture: business entities this API covers and the go-to methods for each. Call with no args to see the whole map ("you are here"); pass entity="reviews" (or stocks/prices/orders/…) to list every method of one entity. Use this before guessing — it orients you fast.
Inputs: entity. Returns: result
hh_remove_cabinetADestructive
Delete a stored cabinet. If it was active, another becomes active.
Args: name: the cabinet to remove.
Inputs: name (required). Returns: result
hh_search_methodsARead-only
Search the endpoint catalog by keyword (works in Russian and English).
Args: query: free text, e.g. "остатки", "stocks", "update price". limit: max results (1-50). Returns JSON list of matching endpoints (best first).
Inputs: query (required), limit. Returns: result
hh_set_keyAIdempotent
Change / rotate the API key from chat (e.g. the old one expired or leaked).
⚠️ The key goes into the chat transcript — requires i_understand_key_goes_to_chat=true. The safe, terminal-free alternative is the installer, where the key never enters chat. Use a scoped key and rotate it in the seller cabinet if it was exposed.
Args: credentials: dict with the required fields ({fields}). cabinet: which cabinet to update. Default: the active one (so "my key expired" just works). If there is none, the cabinet is named from the marketplace's shop name, else "main". i_understand_key_goes_to_chat: must be true to proceed. On success the key is validated against the marketplace and the shop name is reported. Saved locally (chmod 600), never echoed back.
Inputs: credentials (required), cabinet, i_understand_key_goes_to_chat. Returns: result
hh_use_cabinetAIdempotent
Switch the active cabinet. Subsequent API calls use its credentials.
Args: name: the cabinet to activate (see hh_list_cabinets).
Inputs: name (required). Returns: result
hh_write_methodA
Execute one WRITE endpoint from the catalog: create or update data.
Target API: https://api.hh.ru/openapi/specification/public.
Requires confirm_write=true; nothing is sent without it. Irreversible operations live in hh_delete_method, reads in hh_call_method.
Args: operation_id: id from the catalog (see hh_search_methods). path_values: values for {placeholders} in the path. query: query-string parameters. body: JSON request body. confirm_write: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.
Inputs: operation_id (required), body, query, path_values, +1 more. Returns: result
hh_write_rawA
Create or update data at ANY path, including paths not in the catalog.
Target API: https://api.hh.ru/openapi/specification/public.
POST, PUT and PATCH only; requires confirm_write=true.
Args: method: POST, PUT or PATCH. path: full path beginning with '/'. host: host override; defaults to the service's default host. query: query-string parameters. body: JSON request body. confirm_write: must be true. Returns JSON: {"ok": true, "status", "data"} or the error envelope.
Inputs: path (required), method (required), body, host, +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Tools are clearly separated into catalog exploration (list_sections, get_section, describe_method, search_methods, map), execution (call/write/delete_method, raw variants, fetch_all), and cabinet management (list/remove/add/set_key/use_cabinet, check_auth). Some naming overlap like get_section vs get_raw could cause confusion, but descriptions disambiguate catalog-based versus raw endpoints.
All tools share the hh_ prefix and use snake_case. Most follow a verb_noun pattern (list_sections, describe_method, add_cabinet), though 'map' and 'fetch_all' deviate slightly. The pattern is predictable and readable overall.
18 tools is on the higher end but appropriate for a comprehensive API wrapper that covers catalog discovery, execution (read/write/delete), raw fallbacks, pagination, and multi-cabinet credential management. The count reflects the API's complexity without being excessive.
The surface covers the full workflow: discover endpoints, execute any verb, handle pagination, manage credentials/cabinets, and check auth. Raw tools provide escape hatches for uncatalogued endpoints. Minor gaps (e.g., no explicit rate-limit handling) are non-critical for typical use.
Maintenance
Related MCP Connectors
AI model ratings, Gateway prices in rubles, subscriptions and AI jobs in Russia. Read-only, no key.
Search remote jobs, read full postings, and get application links from Claude, Codex, Cursor, and other compatible MCP clients. Tools: search_jobs, get_job, get_filters. Supports cursor pagination and location, category, skill, seniority, employment type, and salary availability filters. Free, read-only Streamable HTTP; no account or API key required. Posting-based facts; remote does not imply worldwide eligibility. Setup: https://heyrole.ai/developers
Jobs, candidates, pipeline and AI interviews from your Humanlike hiring workspace.
Russian APIs for AI agents: YooKassa, CDEK, Bitrix24 and more. Ready scenarios with code. No key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.38MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to access and manage HeadHunter job platform data, including vacancies, resumes, negotiations, and employer settings via 167+ tools.5MIT
- FlicenseAqualityDmaintenanceEnables to interact with hh.ru (a Russian job platform) through browser automation, allowing users to search for jobs, manage resumes, apply to vacancies with cover letters, and track application statuses via natural language.93-
- AlicenseAqualityBmaintenanceEnables searching and retrieving job vacancies, resumes, employers, and salary statistics from the hh.ru API (Russia/CIS) via 19 tools, with optional token access for resume search.1996 npm9MIT