hh

This MCP server exposes a comprehensive set of tools to interact with the HeadHunter API through MCP clients (e.g., Claude, Cursor, VS Code). After starting the server with the provided mcp_config, clients can authenticate using the HeadHunter API credentials (client ID, client secret, user agent, and redirect URI). The server offers a large catalog of endpoints under the Available Tools section, including operations for managing employers, applicants, resumes, vacancies, and various lookups such as locales, regions, and skills. Users can perform actions like reading and updating resumes, creating and managing employer managers, publishing or updating vacancies, and retrieving analytics-like data such as saved searches or vacancy visitors. The tools are designed to be invoked by MCP clients as standard MCP commands, ensuring consistent integration across supported environments.

Prerequisites:

• Node.js version 18.x or newer
• npm or yarn
• HeadHunter API key credentials (HH_CLIENT_ID, HH_CLIENT_SECRET, HH_USER_AGENT, HH_REDIRECT_URI)

Installation steps:

1. Install the MCP server via Smithery (recommended): npx -y @smithery/cli@latest install @sargonpiraev/hh-mcp-server --client <CLIENT_NAME>

2. Alternative manual installation (via npx):

   • Ensure you have your HH credentials ready
   • Use in your MPC client config as shown in the mcp_config section

3. Configure credentials in your environment where you run the MCP server (examples below): HH_CLIENT_ID=your_hh_client_id HH_CLIENT_SECRET=your_hh_client_secret HH_USER_AGENT=your_hh_user_agent HH_REDIRECT_URI=your_hh_redirect_uri

4. Run the server via your chosen integration (Cursor, VS Code, Claude, etc.) using the provided command from the mcp_config.

Notes and tips:

• Ensure your HeadHunter API credentials are kept secure and not committed to source control.
• The server requires Node.js v18+; verify your runtime matches this prerequisite.
• The available tools cover a wide range of HeadHunter API features; if a particular action isn’t returning expected data, validate the input parameters and permissions of the API key.
• When using Cursor/VS Code/Claude integrations, add the environment variables (HH_CLIENT_ID, HH_CLIENT_SECRET, HH_USER_AGENT, HH_REDIRECT_URI) to the respective configuration blocks as shown in the README examples.
• If you encounter authentication issues, double-check the redirect URI registration in your HeadHunter API account and ensure it matches the one configured in your environment.