Headhunter MCP Server

🚀 HeadHunter MCP 服务器

HeadHunter MCP 服务器用于将 HeadHunter API 与 Claude Code 及其他 MCP 客户端集成，帮助 AI 助手在俄罗斯及独联体国家最大的招聘平台 HeadHunter 上搜索职位、管理简历和申请工作。

English | Русский

🚀 快速开始

📦 安装指南

git clone https://github.com/yourusername/headhunter-mcp-server.git
cd headhunter-mcp-server
python -m venv venv
source venv/bin/activate  # 在 Windows 系统中使用：venv\Scripts\activate
pip install -r requirements.txt

🔑 获取 HeadHunter API 凭证

1. 在 https://dev.hh.ru/admin 注册您的应用程序。
2. 获取客户端 ID、客户端密钥和应用令牌。
3. 将 .env.example 复制到 .env 并填写您的凭证。

cp .env.example .env
# 使用您的凭证编辑 .env 文件

⚙️ 配置 Claude Code

在您的 ~/.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"
      }
    }
  }
}

🔐 OAuth 授权（可选）

若要进行职位申请和简历管理，可运行以下命令：

python examples/oauth_flow.py

按照说明进行授权并获取访问令牌。

✨ 主要特性

• 🔍 高级职位搜索：可根据地点、薪资、工作经验和就业类型进行筛选。
• 📄 简历管理：查看和管理您在 HeadHunter 上的简历。
• ✉️ 职位申请：使用自定义求职信申请职位。
• 🏢 公司信息：获取详细的雇主数据。
• 📊 申请跟踪：监控您的求职申请历史。
• 🤖 AI 智能代理：自动搜索职位并进行智能匹配。
• 🔐 OAuth 2.0：与 HeadHunter 进行安全授权。

💻 使用示例

基础用法

# 在莫斯科搜索 Python 开发岗位
Find 10 Python developer vacancies in Moscow with salary from 200000

# 查看您的简历
Show my resumes

# 获取职位详情
Show details for vacancy 126209046

# 申请职位（完成 OAuth 授权后）
Apply to vacancy 126209046 with resume [resume_id] and cover letter: "Hello..."

高级用法

# 启动职位搜索智能代理
Run vacancy-hunter agent

📚 详细文档

可用工具（共 10 个）

1. hh_search_vacancies：搜索职位空缺
2. hh_get_vacancy：获取详细的职位信息
3. hh_get_employer：获取公司/雇主详情
4. hh_get_similar：查找相似的职位
5. hh_get_areas：获取地区/城市列表
6. hh_get_dictionaries：获取参考数据（工作经验、就业类型等）
7. hh_get_resumes：获取您的简历列表
8. hh_get_resume：获取详细的简历信息
9. hh_apply_to_vacancy：申请职位（需要 OAuth 授权）
10. hh_get_negotiations：获取申请历史（需要 OAuth 授权）

职位搜索智能代理

这是一个用于智能搜索和分析职位的自动化代理，更多详细信息请参考 docs/vacancy-hunter-agent.md。

• 特性：
  • 可同时分析多份简历。
  • 根据相关性对职位进行评分（0 - 30 分）。
  • 生成带有 AI 推荐的 CSV 报告。
  • 仅专注于莫斯科地区。

项目结构

headhunter-mcp-server/
├── server.py              # MCP 服务器（包含 10 个工具）
├── hh_client.py           # HeadHunter API 客户端
├── requirements.txt       # Python 依赖项
├── .env.example           # 环境变量模板
├── examples/
│   └── oauth_flow.py      # OAuth 授权脚本
└── docs/
    └── vacancy-hunter-agent.md  # 代理文档

要求

• Python 3.10 及以上版本
• Claude Code 或任何兼容 MCP 的客户端
• HeadHunter API 凭证

贡献

欢迎贡献代码！请随时提交 Pull Request。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🔗 链接

• HeadHunter API 文档
• Model Context Protocol
• Claude Code 文档

❤️ 为 HeadHunter 和 MCP 社区精心打造