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 社區精心打造