Headhunter MCP Server

🚀 HeadHunter MCP Server

This is an MCP (Model Context Protocol) server that integrates the HeadHunter API with Claude Code and other MCP clients. It facilitates seamless interaction between AI assistants and the HeadHunter platform, enabling functions such as job search, resume management, and job application.

🚀 Quick Start

1. Installation

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

2. Get HeadHunter API Credentials

1. Register your application at https://dev.hh.ru/admin.
2. Obtain the Client ID, Client Secret, and App Token.
3. Copy .env.example to .env and fill in your credentials.

cp .env.example .env
# Edit .env with your credentials

3. Configure Claude Code

Add the following to your ~/.claude.json:

{
  "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"
      }
    }
  }
}

4. OAuth Authorization (Optional)

For job applications and resume management, run:

python examples/oauth_flow.py

Follow the instructions to authorize and get access tokens.

✨ Features

• 🔍 Advanced Vacancy Search: Filter by location, salary, experience, employment type.
• 📄 Resume Management: View and manage your HeadHunter resumes.
• ✉️ Job Applications: Apply to vacancies with custom cover letters.
• 🏢 Company Information: Get detailed employer data.
• 📊 Application Tracking: Monitor your job application history.
• 🤖 AI-Powered Agent: Automated vacancy hunter with intelligent matching.
• 🔐 OAuth 2.0: Secure authorization with HeadHunter.

📦 Available Tools (10)

1. hh_search_vacancies: Search for job vacancies.
2. hh_get_vacancy: Get detailed vacancy information.
3. hh_get_employer: Get company/employer details.
4. hh_get_similar: Find similar vacancies.
5. hh_get_areas: Get list of regions/cities.
6. hh_get_dictionaries: Get reference data (experience, employment types, etc.).
7. hh_get_resumes: Get your resumes list.
8. hh_get_resume: Get detailed resume information.
9. hh_apply_to_vacancy: Apply to a vacancy (requires OAuth).
10. hh_get_negotiations: Get application history (requires OAuth).

💻 Usage Examples

Basic Usage

# Search for Python jobs in Moscow
Find 10 Python developer vacancies in Moscow with salary from 200000

# View your resumes
Show my resumes

# Get vacancy details
Show details for vacancy 126209046

# Apply to a job (after OAuth)
Apply to vacancy 126209046 with resume [resume_id] and cover letter: "Hello..."

🤖 Vacancy Hunter Agent

This is an automated agent for intelligent vacancy search and analysis. For more details, see docs/vacancy-hunter-agent.md.

Features

• Analyzes multiple resumes simultaneously.
• Scores vacancies by relevance (0 - 30 points).
• Generates CSV reports with AI-powered recommendations.
• Focuses on the Moscow region only.

Usage

Run vacancy-hunter agent

🏗️ Project Structure

headhunter-mcp-server/
├── server.py              # MCP server (10 tools)
├── hh_client.py           # HeadHunter API client
├── requirements.txt       # Python dependencies
├── .env.example           # Environment variables template
├── examples/
│   └── oauth_flow.py      # OAuth authorization script
└── docs/
    └── vacancy-hunter-agent.md  # Agent documentation

⚙️ Requirements

• Python 3.10+
• Claude Code or any MCP-compatible client
• HeadHunter API credentials

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is under the MIT License. See the LICENSE file for details.

🔗 Links

• HeadHunter API Documentation
• Model Context Protocol
• Claude Code Documentation

Made with ❤️ for the HeadHunter and MCP community