This MCP server provides an integration layer between the HeadHunter API and MCP clients (such as Claude Code). It exposes tools to search vacancies, fetch vacancy and employer details, manage resumes, and apply to jobs, all via MCP commands. The server supports OAuth for actions that require user authorization (like applying to vacancies or managing resumes). To use it, run the server and point your MCP client to the server script; typical workflows include searching for vacancies, inspecting job details, and initiating applications with an attached resume and cover letter. The included tools correspond to 10 endpoints: hh_search_vacancies, hh_get_vacancy, hh_get_employer, hh_get_similar, hh_get_areas, hh_get_dictionaries, hh_get_resumes, hh_get_resume, hh_apply_to_vacancy, and hh_get_negotiations. If OAuth is required for an action, you will need to complete the authorization flow to obtain access tokens.

Prerequisites:

• Python 3.10+ installed on your system
• Access to HeadHunter API credentials (Client ID, Client Secret, App Token)
• A suitable MCP client (e.g., Claude Code) to connect to the MCP server

Step-by-step:

1. Clone the repository: git clone https://github.com/yourusername/headhunter-mcp-server.git cd headhunter-mcp-server

2. Set up a Python virtual environment: python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies: pip install -r requirements.txt

4. Prepare environment variables:

   • Copy the example env file if provided and fill in your credentials cp .env.example .env

     Edit .env with your HH credentials

   • Ensure the following are set (either in .env or in the environment): HH_CLIENT_ID, HH_CLIENT_SECRET, HH_APP_TOKEN, HH_REDIRECT_URI

5. Run the MCP server: python server.py

6. Configure your MCP client (e.g., Claude Code) to connect to the server using the appropriate command and arguments, for example:

   • Command: python
   • Arguments: ["server.py"]
   • Environment variables: HH_CLIENT_ID, HH_CLIENT_SECRET, HH_APP_TOKEN, HH_REDIRECT_URI

Notes:

• If you are using a virtual environment, ensure the path to Python in your client configuration points to the venv Python executable.
• For actions requiring OAuth, run the OAuth flow per the README and fetch the access tokens before making registry calls.

Tips and common issues:

• Ensure your HH credentials have the necessary scopes for the actions you intend to perform (vacancies search, resumes, applications).
• If you encounter rate limiting from HeadHunter, consider adding request throttling in client calls or distributing calls across sessions.
• The OAuth flow (for applying to vacancies and managing resumes) requires a valid redirect URI. Ensure your redirect URI is registered in your HeadHunter app settings and matches the value in HH_REDIRECT_URI.
• If you modify server.py or tool handlers, restarting the MCP server is required to pick up changes.
• Keep your dependencies up to date by periodically running pip install -r requirements.txt.
• This MCP server expects to be used with an MCP-compatible client; consult the MCP documentation for exact request formats and response handling.