Skip to main content
Glama
ati-hh-mcp

ati-hh-mcp

by timur-ai

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
HH_TOKENNohh.ru token for all calls (stdio path; ignored in HTTP mode with MCP_API_KEYS).
HH_API_BASENoAPI base URL (tests and experiments).https://api.hh.ru
HH_TOOLSETSNoComma-separated toolsets to enable; fully replaces the default list (auth is always included).
HH_UA_EMAILNoContact email in the User-Agent (hh.ru requirement).placeholder
HH_CLIENT_IDNoOAuth application client id from dev.hh.ru.
MCP_API_KEYSNoComma-separated API keys guarding the HTTP endpoint (case-sensitive).
HH_RATE_LIMITNoRequests per minute (token bucket).25
HH_TOKEN_STORENoSQLite path for OAuth token pairs (Docker: /data/tokens.sqlite3).platform dir
HH_REDIRECT_URINoOAuth redirect URI registered at dev.hh.ru.
HH_CLIENT_SECRETNoOAuth application client secret.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

MCP server for the hh.ru API. Tools are grouped into switchable toolsets; call the dict_* tools first to resolve ids for search parameters. Errors come as structured messages with hh.ru error codes and Russian descriptions.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": true
}
logging
{}
prompts
{
  "listChanged": true
}
resources
{
  "subscribe": false,
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
get_meA

Get information about the current hh.ru user (GET /me).

Requires an hh.ru token (HH_TOKEN env, X-HH-Token header or OAuth profile). If the token has expired, the server refreshes the OAuth pair and retries the request once.

auth_get_login_urlA

Get the hh.ru OAuth login URL (manual code copy flow).

Returns the authorize URL and Russian instructions: open the URL, log in on hh.ru, copy the code query parameter from the redirect address and pass it to auth_exchange_code.

auth_exchange_codeA

Exchange an hh.ru OAuth authorization code for token pair.

Use after auth_get_login_url: pass the code parameter copied from the redirect address. Tokens are stored in the local profile.

auth_statusA

Show OAuth configuration and stored token status.

Reports whether OAuth client credentials are configured, whether a token pair is stored for the current profile (the request profile in HTTP mode, default otherwise), and when it was obtained.

auth_logoutA

Revoke the hh.ru OAuth token and delete the local profile.

Calls DELETE /token on hh.ru (invalidates the token pair) and removes stored tokens. Mutation: requires confirm=True.

dict_dictionariesA

Get hh.ru core dictionaries: currencies, genders, vacancies statuses and other enumerations used across the API.

dict_areasB

Get the full tree of hh.ru regions (areas): countries, federal subjects and cities, with their numeric ids. Optional additional_case=prepositional adds a Russian prepositional-case name.

dict_area_countriesA

Get the list of countries known to hh.ru with their numeric ids (each country is also an area).

dict_areaA

Get one hh.ru region (area) by its numeric id, including nested children. Optional additional_case=prepositional adds a Russian prepositional-case name.

dict_industriesA

Get the tree of industries (spheres of company activity) with sub-industries and their ids.

dict_professional_rolesA

Get the tree of professional roles (job categories) with sub-categories and their numeric ids; role ids are used in vacancy and resume search.

dict_languagesA

Get the dictionary of foreign languages with their ids.

dict_localesB

Get the locales supported by hh.ru (vacancy interface).

dict_resume_localesA

Get the locales supported in hh.ru resumes.

dict_districtsA

Get the administrative districts of Russian cities (district ids narrow down a vacancy search within a city).

dict_metroA

Get metro lines and stations for all hh.ru cities that have a metro map, grouped by city with station ids.

dict_metro_cityB

Get metro lines and stations of a single city by area id (for example 4 = Moscow).

dict_skillsA

Get key skills by id (one or several; up to 50 values per request). Find skill ids with suggest_skill_set.

dict_educational_institutionsA

Get educational institutions by id (up to 50 values per request). Find institution ids with suggest_educational_institutions.

dict_facultiesC

Get the faculty list of one educational institution by its id.

dict_vacancy_conditionsA

Get the dictionary of paid vacancy placement conditions (branded templates, priority placement and similar options).

suggest_areasA

Suggest hh.ru regions (areas) by name prefix; returns matching areas with ids. area_id narrows the search to children of a given region, include_parent=true adds the parent region to the response.

suggest_area_leavesA

Suggest leaf regions (cities/districts without children) inside area_id by name prefix; used to pick concrete locations.

suggest_companiesA

Suggest registered employers (companies) by name prefix with their ids and urls.

suggest_educational_institutionsB

Suggest educational institutions by name prefix with their ids.

suggest_fields_of_studyA

Suggest fields of study (specialties) by name prefix with their ids for resume and vacancy education blocks.

suggest_positionsA

Suggest job positions (titles) by name prefix for resumes; returns positions with professional role ids.

suggest_professional_rolesB

Suggest professional roles by name prefix with their ids for vacancy and resume search.

suggest_resume_search_keywordA

Suggest full search phrases for resume search by a partial keyword (employer side).

suggest_skill_setB

Suggest key skills by name prefix with their ids; skill ids are accepted by dict_skills.

suggest_vacancy_positionsA

Suggest job positions (titles) by name prefix for vacancies; returns positions with professional role ids.

suggest_vacancy_search_keywordB

Suggest full search phrases for vacancy search by a partial keyword (applicant side).

search_vacanciesA

Search vacancies on hh.ru. Frequent filters (text, area, salary, currency, experience, employment, schedule, search_field, page, per_page, order_by and others) are top-level parameters. Rare or niche filters are grouped into the nested advanced object: pass only the fields you need, unset fields are not sent. Resolve ids first: dict_areas, dict_professional_roles, dict_industries, dict_metro. The response includes found, pages and clusters for pagination.

get_vacancyB

Get full details of one vacancy by its numeric id, including salary, key skills, contacts and branded description.

similar_vacanciesC

Get vacancies similar to the given vacancy id; supports the same frequent filters as search_vacancies plus the nested advanced object for rare filters.

related_vacanciesC

Get other vacancies of the employer that published the given vacancy; supports frequent filters plus the nested advanced object for rare filters.

list_negotiationsB

List negotiations (responses and invitations) of the current user. Filter by status, vacancy or unread updates; ordered by last update (newest first) by default. The response contains collections with actions URLs used by other negotiation tools.

get_negotiationA

Get full information about a single negotiation (response or invitation) by its id, including messages URL and available state actions.

update_negotiationA

Apply a collection action (for example invite or decline) to one or more negotiations. The {id} path value and required body arguments (topic_id, message, send_sms and others) come from actions[].url and actions[].arguments of the negotiation list. Mutation: requires confirm=True.

move_negotiationB

Change the employer or applicant state of a negotiation by moving it to another collection (for example from response to invitation). collection_name and nid come from the actions URL of the negotiation; an optional message can be attached. Mutation: requires confirm=True.

list_negotiation_messagesB

List all messages of a negotiation (response or invitation) thread. Note: hh.ru considers negotiation messaging legacy and recommends chats; use with_text_only to skip service messages.

send_negotiation_messageB

Send a new message inside a negotiation thread. Sending is possible while the conversation is open (see the hh.ru rules for negotiations). Mutation: requires confirm=True.

list_collection_negotiationsC

List negotiations of the unsorted responses collection ("/response") of a vacancy with resume-like filters: area, experience, education, salary range, age and others. The same URL pattern serves other collections: replace the last path segment with the collection id from the collections list.

mark_negotiations_readA

Mark negotiations as read. topic_id values in the body must belong to one vacancy (up to 50 ids). Mutation: requires confirm=True.

request_phone_interviewA

Invite an applicant to a vacancy by resume: creates an invitation negotiation, optionally sends an email message and an SMS notification. resume_id and vacancy_id are required in the body (sent form-encoded per the vendor spec). Mutation: requires confirm=True.

get_negotiation_test_solutionC

Get the results of tests completed by the applicant of a negotiation (attached to the vacancy).

list_chatsB

List chats of the current user (applicant or employer) with pagination and filters: unread only, with text messages, by vacancy status or explicit vacancy ids.

get_unread_countersA

Get the number of unread chats for the current user (total and with new messages).

get_chat_file_conditionsA

Get conditions for files attached to chat messages: allowed formats, size limits and other constraints.

create_chat_file_upload_linkA

Create a one-time upload link for a chat file attachment. Upload the file with a multipart POST (field 'file') to the returned URL, then send the message with the received file_upload_id (see send_chat_message). Check get_chat_file_conditions first. Mutation: requires confirm=True.

create_chat_without_vacancyA

Get an existing chat or create a new one bound to a resume without a specific vacancy (resume_hash is required, an optional first_message opens the conversation). Mutation: requires confirm=True.

leave_chatC

Leave the given chat. Mutation: requires confirm=True.

mark_chat_message_readB

Mark the message as the last viewed one in the chat (updates unread counters). Mutation: requires confirm=True.

list_chat_messagesB

List messages of a chat, starting from start_message_id in the given order (next or prev) with a limit (default 10).

send_chat_messageA

Send a message to a chat: either a text message ({"text": "..."}) or a file ({"file_upload_id": "..."} from create_chat_file_upload_link). Mutation: requires confirm=True.

update_chat_messageB

Edit the text of your own message in a chat. Mutation: requires confirm=True.

delete_chat_messageA

Delete your own message from a chat. Mutation: requires confirm=True.

get_chat_participantsC

List participants of the chat: the applicant and employer managers involved in the conversation.

update_chat_participantsB

Add an employer manager to the chat (body: manager id). Mutation: requires confirm=True.

set_chat_write_possibilityA

Enable or disable the applicant's right to write messages in the chat (employer side; applicant_write_possibility is sent as a query parameter). Mutation: requires confirm=True.

get_resumeA

Get a resume by id or hash: own resume for an applicant or an accessible resume for an employer. Optional flags add contact credentials, job search status and negotiation history.

get_resume_phoneA

Get the phone number of a resume through hh.ru call tracking (employer side; the call is logged by hh.ru).

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

B3.1/5.0

Scored across 62 tools

Disambiguation3/5

Most tools target a distinct resource+action, but with 62 tools there are several near-pairs that require careful reading: dict_areas vs suggest_areas vs suggest_area_leaves, dict_metro vs dict_metro_city, suggest_positions vs suggest_vacancy_positions vs suggest_professional_roles, and list_negotiations vs list_collection_negotiations. Descriptions do clarify the boundaries (resume-side vs vacancy-side, legacy negotiations vs chats), but an agent can still misselect without close attention.

Naming Consistency4/5

Names follow a predictable, readable pattern of domain prefix + verb/noun (dict_*, suggest_*, auth_*, chat_*, negotiation_*), with clear verb_noun forms like get_resume, list_chats, send_chat_message, delete_chat_message. Minor deviations exist (e.g. get_me, similar_vacancies, related_vacancies lack a domain prefix, and auth_get_login_url mixes prefix and verb), but the overall scheme is coherent.

Tool Count2/5

62 tools far exceeds the 3-15 sweet spot and makes the surface hard for an agent to navigate; many niche dictionary/suggest endpoints could be consolidated or lazily exposed. Each tool does map to a real hh.ru endpoint, so it is not arbitrary bloat, but the count is still excessive for practical selection.

Completeness3/5

Coverage is broad across dictionaries, OAuth, negotiations, and chats (including message CRUD, file uploads, and participant management), so core workflows are reachable. However, key lifecycle operations are missing: resumes and vacancies are read-only (no create/update/publish), and applicant-side/employer-side applicant search tools are absent, leaving notable gaps.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues