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

MCP serverRussian stack

mardanaltynbekov1104/hh-mcpAuthor:Mardan Altynbekov

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/mardanaltynbekov1104-hh-mcp

Detects the agents on your machine, checks the risk and pins the version.

Other ways to install

This entry is high risk, so there is no one-click install. Review the code and add the config by hand.

Run in a terminal

claude mcp add --transport stdio --env 'HH_CLIENT_ID=<your HH_CLIENT_ID>' --env 'HH_CLIENT_SECRET=<your HH_CLIENT_SECRET>' --env 'HH_USER_AGENT=<HH_USER_AGENT value>' hh -- npx tsx /Users/you/apps/hh-mcp/src/index.ts

Or add to the file .mcp.json, in the project

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.cursor/mcp.json, for all projects

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. For a single project, put the same block into .cursor/mcp.json.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Run in a terminal

code --add-mcp '{"name":"hh","type":"stdio","command":"npx","args":["tsx","/Users/you/apps/hh-mcp/src/index.ts"],"env":{"HH_CLIENT_ID":"<your HH_CLIENT_ID>","HH_CLIENT_SECRET":"<your HH_CLIENT_SECRET>","HH_USER_AGENT":"<HH_USER_AGENT value>"}}'

Or add to the file .vscode/mcp.json, in the project

{
  "servers": {
    "hh": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the servers key.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Run in a terminal

codex mcp add hh --env 'HH_CLIENT_ID=<your HH_CLIENT_ID>' --env 'HH_CLIENT_SECRET=<your HH_CLIENT_SECRET>' --env 'HH_USER_AGENT=<HH_USER_AGENT value>' -- npx tsx /Users/you/apps/hh-mcp/src/index.ts

Or add to the file ~/.codex/config.toml, for all projects

[mcp_servers.hh]
command = "npx"
args = ["tsx", "/Users/you/apps/hh-mcp/src/index.ts"]
env = { HH_CLIENT_ID = "<your HH_CLIENT_ID>", HH_CLIENT_SECRET = "<your HH_CLIENT_SECRET>", HH_USER_AGENT = "<HH_USER_AGENT value>" }

If the file already exists, append the block to the end.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Run in a terminal

gemini mcp add -s user -e 'HH_CLIENT_ID=<your HH_CLIENT_ID>' -e 'HH_CLIENT_SECRET=<your HH_CLIENT_SECRET>' -e 'HH_USER_AGENT=<HH_USER_AGENT value>' hh npx tsx /Users/you/apps/hh-mcp/src/index.ts

Or add to the file ~/.gemini/settings.json, for all projects

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.config/devin/mcp_config.json, for all projects

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. Legacy Cascade keeps the MCP config in ~/.codeium/windsurf/mcp_config.json.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Formerly Windsurf.

Add to the file cline_mcp_settings.json, for all projects

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. Open the settings file in Cline: MCP Servers tab, Configure MCP Servers.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file .roo/mcp.json, in the project

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

A fork of Roo Code, same .roo folders.

Add to the file opencode.json, in the project

{
  "mcp": {
    "hh": {
      "type": "local",
      "command": [
        "npx",
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "environment": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcp key.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.config/zed/settings.json, for all projects

{
  "context_servers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the context_servers key.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file .codeassistant/mcp.json, in the project

{
  "mcpServers": {
    "hh": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/apps/hh-mcp/src/index.ts"
      ],
      "env": {
        "HH_CLIENT_ID": "<your HH_CLIENT_ID>",
        "HH_CLIENT_SECRET": "<your HH_CLIENT_SECRET>",
        "HH_USER_AGENT": "<HH_USER_AGENT value>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

HH_CLIENT_IDsecret, required
HH_CLIENT_SECRETsecret, required
HH_USER_AGENTrequired

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

You will need: Node.js

Checked against the repository on Sep 25, 2026, commit 69e389a.

Text for your agent

Create an employer OAuth app at dev.hh.kz/admin or dev.hh.ru/admin, clone the repository, run npm install, fill in HH_CLIENT_ID, HH_CLIENT_SECRET and HH_USER_AGENT in .env, connect the server over stdio, call hh_auth action=get_auth_url, authorize, and pass the code to hh_auth action=exchange_code.

Other ways from the author

git clone https://github.com/mardanaltynbekov1104/hh-mcp.git ~/apps/hh-mcp && cd ~/apps/hh-mcp && npm install && cp .env.example .env

Setup from the README; you then need to fill in HH_CLIENT_ID, HH_CLIENT_SECRET and HH_USER_AGENT.

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

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.

MCP

Transport: stdio, http
Authentication: OAuth

Environment variables
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.

Security check

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

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.

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.

SiYuan

Official

A self-hosted knowledge base with block-level references and a built-in MCP server for connecting AI agents to your notes

MCP serverMedium risk46.5K

gws

Editors’ pick

A CLI for every Google Workspace API with JSON output and agent skills: Drive, Gmail, Calendar, Sheets and more

CLIHigh risk31.2K

QMD

Editors’ pick

Local search over Markdown notes, docs and meeting transcripts: keywords, semantic search and reranking, with an MCP server

CLIMedium riskNo VPN needed30.1K

Taskmaster

Editors’ pick

A task manager for AI-driven development: breaks a PRD into dependent tasks and guides the agent through them via MCP or CLI

MCP serverMedium risk28.1K

Install

What it does

Good fit when

Not a fit when

Example request

Limitations

MCP

Security check

README in short

FAQ

Related

SiYuan

gws

QMD

Taskmaster