SkillFoxx

hh-mcp: hh.ru and hh.kz employer API

hh-mcp

An MCP server for the employer side of the hh.ru and hh.kz API: your vacancies, applications, resume search, sourcing and webhooks through an OAuth app

  • 1 ★ on the repository
  • Last commit
  • MIT
MCP server

Broad access

Why this level

  • Can invite a candidate and send a message on the employer's behalf (hh_employer_negotiations invite, message_send)
  • Viewing a resume spends a paid employer contact, so a mistaken call costs money
  • The employer OAuth tokens grant broad access to vacancies, applications and candidate resumes
All reasons and checks
Russian stack

mardanaltynbekov1104/hh-mcpAuthor:Mardan Altynbekov

Install

Services

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/mardanaltynbekov1104-hh-mcp

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Broad accessThe tool can change data, run commands or handle secrets.

  • Can invite a candidate and send a message on the employer's behalf (hh_employer_negotiations invite, message_send)
  • Viewing a resume spends a paid employer contact, so a mistaken call costs money
  • The employer OAuth tokens grant broad access to vacancies, applications and candidate resumes

This is third-party code. Review the repository files before installing.

What it does

Nine tools cover more than 70 actions of HeadHunter's official employer API (hh.kz and hh.ru share the same API). hh_auth walks through the OAuth flow from the authorization link to saving tokens in ~/.hh-mcp/tokens.json with 600 permissions and auto-refresh on expiry. hh_employer_vacancies manages your vacancies: active, archived and hidden lists, CRUD, archiving, renewal, drafts, statistics and visitors. hh_employer_negotiations reads and moves applications through pipeline stages, sends messages to candidates, invites a candidate to a vacancy, and stores message templates. hh_employer_resumes searches resumes under a paid subscription; fetching a specific resume needs explicit confirm: true because it spends a paid contact, and the same tool handles saved-search CRUD and team notes about a candidate. hh_webhooks subscribes to real-time events like a new application. The public parts (reference data, autocomplete, salary estimates) work without OAuth.

Who it is for. For HR managers and recruiters with an hh.kz or hh.ru employer account who want to manage vacancies, applications and candidate sourcing from an agent.

Good fit when

  • You need to manage your vacancies, applications and candidate correspondence through an agent
  • You need sourcing: subscription resume search and inviting matching candidates
  • You need real-time webhooks for new applications or status changes

Not a fit when

  • You're a job seeker, not an employer: the README explicitly says the applicant side is still on the roadmap
  • You have no employer OAuth app at dev.hh.kz or dev.hh.ru: without client_id and client_secret the employer tools don't work
  • You're not ready to pay for resume views: fetching a resume requires confirm: true precisely because it spends a paid contact

Example request

Show new applications for vacancy 12345678 and suggest a reply inviting the candidate to a Zoom interview

MCP

Transport
stdio, http
Authentication
OAuth

Environment variables

HH_CLIENT_ID required, secret
OAuth client id from dev.hh.kz or dev.hh.ru, needed for the employer tools.
HH_CLIENT_SECRET required, secret
The OAuth client secret for the same app.
HH_USER_AGENT required
A User-Agent string with a contact email; hh.kz and hh.ru require it in the header.

Limitations

This is version 0.1, and the author calls it an employer-side MVP. The applicant side, webhooks without your own public HTTPS receiver, and convenient distribution like Railway or a DXT bundle are on the roadmap, not ready. hh_webhooks needs your own public HTTPS URL to receive events, which you have to stand up separately. Opening a specific resume spends a paid employer contact, so a mistaken confirm: true isn't free.

How to disable. Remove the hh block from mcpServers in your client configuration and delete ~/.hh-mcp/tokens.json with the saved tokens.

FAQ

Does the server work for a job seeker rather than an employer?

No, this is an employer-side MVP; applicant-side tools are on the roadmap for version 0.2+.

Why does fetching a resume need separate confirmation?

Because viewing a specific resume spends a paid employer contact, so the tool requires an explicit confirm: true.

Discussion

No questions or reviews yet.

All hh.ru tools
Russian stack

An hh.ru API MCP server for job seekers: vacancy search, employer data, your resumes and applications with cover letters

MCP serverBroad access39

hh.ru MCP

hh-mcp

Russian stack

MCP server for the hh.ru API: vacancy and employer search, salary estimates, reference lists, resumes with employer access

MCP serverExtended access10
Russian stack

An MCP server with 52 tools over the official hh.ru API: vacancy search with no token, employer resumes and applications with one, and salary statistics

MCP serverExtended access
Russian stack

A FastMCP server with 43 hh.ru tools: signs in via the official hh.ru Android app's OAuth, no need to register your own app at dev.hh.ru

MCP serverBroad access
Russian stack

A browser-based MCP server for job search on hh.ru: resume-matched vacancy recommendations, applications and statuses

MCP serverBroad access3

README in short

The README lists nine tools covering more than 70 actions of HeadHunter's employer API, a table of the auth level for each, install steps and the OAuth flow with token storage, configs for Claude Code, Claude Desktop, Cursor, Continue and Cline, plus an HTTP mode for the claude.ai connector. It gives extensive call examples: vacancy search, applications, inviting a candidate, resume search and viewing, candidate notes, webhook subscriptions. The roadmap includes the new chat API, billing, the applicant side and Railway hosting. MIT license.

README badge

Report a problem