hh-mcp-ru: 133 hh.ru API methods with a write gate

hh-mcp-ru

An MCP server over the official hh.ru API: a catalog of 133 methods, keyword method search, and mandatory confirmation before any write action

MCP serverRussian stack

ilyautov/hh-mcp-ruAuthor:Ilya Utov

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/hh-mcp-ru

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

Other ways to install

Run in a terminal

claude mcp add --transport stdio hh-mcp-ru -- uvx hh-mcp-ru==0.3.0

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

{
  "mcpServers": {
    "hh-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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

Install in Cursor

The button opens the agent and offers to add the server. If nothing happens, copy the config below.

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

{
  "mcpServers": {
    "hh-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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

Install in VS Code

The button opens the agent and offers to add the server. If nothing happens, copy the config below.

Run in a terminal

code --add-mcp '{"name":"hh-mcp-ru","type":"stdio","command":"uvx","args":["hh-mcp-ru==0.3.0"]}'

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

{
  "servers": {
    "hh-mcp-ru": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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-mcp-ru -- uvx hh-mcp-ru==0.3.0

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

[mcp_servers.hh-mcp-ru]
command = "uvx"
args = ["hh-mcp-ru==0.3.0"]

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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 hh-mcp-ru uvx hh-mcp-ru==0.3.0

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

{
  "mcpServers": {
    "hh-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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-mcp-ru": {
      "type": "local",
      "command": [
        "uvx",
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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-mcp-ru": {
      "command": "uvx",
      "args": [
        "hh-mcp-ru==0.3.0"
      ]
    }
  }
}

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

Keys and settings

HH_TOKENsecret, optional: Токен приложения hh.ru (dev.hh.ru → Мои приложения).
HH_APP_NAMEoptional: Имя приложения и контактный email для заголовка HH-User-Agent: без него hh отклоняет запросы.

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

You will need: uv

Checked against the repository on Sep 25, 2026, commit 1c6bf53.

Text for your agent

Get a token at dev.hh.ru → My Applications → create an application, install the server with uvx hh-mcp-ru, set the HH_TOKEN and, critically, HH_APP_NAME variables in your MCP client config, then find the right method with hh_search_methods and confirm writes with confirm_write when calling hh_write_method.

Other ways from the author

uvx hh-mcp-ru

Run without installing via uv, for clients with a terminal.

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

What it does

The 133-method catalog is built directly from hh.ru's official OpenAPI spec (api.hh.ru/openapi/specification/public) and lives in the repository as hh_mcp/endpoints.yaml, so the method table can't drift from the code: 92 read, 32 write, 9 irreversible. Instead of 133 separate tools, the agent gets a handful of generic ones: hh_search_methods finds the right method by keyword, hh_describe_method shows its parameters and access class, hh_call_method reads without confirmation, hh_write_method requires passing confirm_write, and irreversible actions require confirming twice. The server supports multiple hh.ru accounts and stores them in ~/.ru-mcp/cabinets.json with 600 permissions outside the repository. The uvx hh-mcp-ru doctor command checks the install and keys without revealing secrets, and with --live it makes one cheap real read call.

Who it is for. For HR managers and recruiters with an hh.ru app who want the full official API in an agent chat, but with confirmation before any vacancy change or application action.

Good fit when

You need the full official hh.ru API (vacancies, applications, resumes, reference data, salary statistics), not just a slice of it
It matters that writes and irreversible actions require explicit confirmation rather than executing immediately
You need to export your vacancies and applications for a period, or check competitor salaries before posting

Not a fit when

You have no access to dev.hh.ru and an hh.ru app with a token: the server only works through the official API with a token
You need automation outside the official API, like browser-emulated auto-apply: this server strictly goes through hh.ru's API
You need a static tool per method: here it's three or four generic tools instead of 133

Example request

Export my vacancies and their applications for the last month into a table

Limitations

It needs an hh.ru app token from dev.hh.ru with HH_APP_NAME filled in, otherwise hh.ru rejects requests with an unclear User-Agent as a 400 error. The project comes from a single author and is part of a broader platform of several MCP servers (vk-mcp-ru, diadoc-mcp-ru, sbis-mcp-ru, chestny-znak-mcp-ru, marketplaces-mcp-ru) sharing the schema-mcp-core package. Of the 133 methods, 9 are marked irreversible, and even double confirmation doesn't protect against a mistake in the request itself.

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

MCP

Transport: stdio
Authentication: API key

Environment variables
Environment variables
HH_TOKEN required, secret	An hh.ru app token, issued at dev.hh.ru under My Applications.
HH_APP_NAME required	The app name and contact email for the HH-User-Agent header, mandatory: without it hh.ru rejects requests with a 400 error.

Security check

Grants access to 32 write methods and 9 irreversible actions like deletion, though all of them require confirmation
The hh.ru app token grants access to vacancies, applications and candidate correspondence and must be kept secret

README in short

The README describes a 133-method catalog built from hh.ru's official spec, broken into sections with an access class for each. It shows two install paths: an .mcpb file for terminal-free Claude Desktop setup and uvx for other clients, how to get a token at dev.hh.ru, an environment variable table, and a doctor diagnostic command. A separate security section explains the three access classes and write confirmation; a privacy policy section confirms no telemetry. The author maintains a family of similar MCP servers for other Russian services on a shared core. MIT license.

FAQ

Can the server publish or delete a vacancy without asking?

No, a write requires passing confirm_write, and irreversible actions like deletion require confirming twice.

Why does hh.ru return a 400 error right after install?

Most likely HH_APP_NAME is unset: hh.ru rejects requests without a proper HH-User-Agent header.

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 risk30.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