HeadHunter MCP Server

How to use

Connect your MCP client to the HeadHunter MCP Server and use its tools to search for vacancies, view vacancy and employer details, manage resumes, and apply to vacancies with personalized cover letters. You can authorize via OAuth for actions that require access to your HeadHunter account, then run automated agent workflows to hunt for suitable roles and track applications.

How to install

Prerequisites you need before starting:

# 1) Install Python 3.10 or newer
# 2) Install virtual environment support if not already available
# 3) Ensure you have network access for package installation

Step-by-step installation and setup:

git clone https://github.com/yourusername/headhunter-mcp-server.git
cd headhunter-mcp-server
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Prepare HeadHunter API credentials and environment file:

cp .env.example .env
# Edit .env with your credentials: HH_CLIENT_ID, HH_CLIENT_SECRET, HH_APP_TOKEN, HH_REDIRECT_URI

Configure Claude Code to load the MCP server from your virtual environment and server script. Create or edit your ~/.claude.json with the following content (adjust paths to your environment and server script):

{
  "mcpServers": {
    "headhunter": {
      "type": "stdio",
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/headhunter-mcp-server/server.py"],
      "env": {
        "HH_CLIENT_ID": "your_client_id",
        "HH_CLIENT_SECRET": "your_client_secret",
        "HH_APP_TOKEN": "your_app_token",
        "HH_REDIRECT_URI": "https://your-domain.com/oauth/callback"
      }
    }
  }
}

If you plan to use OAuth for actions like applying to vacancies or managing resumes, you can run the OAuth flow script to obtain access tokens. Execute the script and follow the prompts to authorize access.

Additional sections

Project structure and key components help you understand what runs where. The MCP server includes the main server script, an HTTP client for HeadHunter interactions, dependencies, environment templates, and OAuth flow tooling. Typical files you’ll interact with include the server script, client module, and example OAuth script.

Security note: keep your credentials secure. Store them in the environment file and avoid sharing your OAuth tokens or client secrets. Use the OAuth flow for long-term access where appropriate and rotate credentials if you suspect exposure.

Usage notes and examples demonstrate common tasks you can perform once connected: search vacancies, view resumes, inspect vacancies, and apply to roles with optional cover letters. You can also leverage the Vacancy Hunter Agent for automated, multi-resume analysis and AI-driven recommendations focused on the Moscow region.

Project structure you will see in the repository includes the MCP server, an HH client, a requirements file, an environment template, an OAuth example, and docs for the agent.

hh_search_vacancies

Search for job vacancies with filters such as location, salary, experience, and employment type.

hh_get_vacancy

Get detailed information about a specific vacancy.

hh_get_employer

Retrieve company/employer details.

hh_get_similar

Find vacancies similar to a given one.

hh_get_areas

Get a list of regions and cities.

hh_get_dictionaries

Fetch reference data such as experience levels and employment types.

hh_get_resumes

Get the list of your resumes.

hh_get_resume

Get detailed information for a specific resume.

hh_apply_to_vacancy

Submit an application to a vacancy (requires OAuth).

hh_get_negotiations

Retrieve your application history (requires OAuth).