Headhunter MCP Server

🚀 HeadHunter MCP Server

このMCP（Model Context Protocol）サーバーは、HeadHunter APIをClaude Codeやその他のMCPクライアントと統合するためのものです。HeadHunter（hh.ru）は、ロシアとCIS諸国で最大の求人情報プラットフォームです。このサーバーを通じて、AIアシスタントが求人検索、履歴書管理、求職活動を代行できます。

🚀 クイックスタート

1. インストール

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

2. HeadHunter APIの資格情報を取得

1. https://dev.hh.ru/admin でアプリケーションを登録します。
2. Client ID、Client Secret、App Tokenを取得します。
3. .env.example を .env にコピーし、取得した資格情報を記入します。

cp .env.example .env
# .envを編集して資格情報を入力

3. 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"
      }
    }
  }
}

4. OAuth認証（オプション）

求職活動や履歴書管理を行う場合は、以下のコマンドを実行します。

python examples/oauth_flow.py

指示に従って認証し、アクセストークンを取得します。

✨ 主な機能

• 🔍 高度な求人検索 - 勤務地、給与、経験、雇用形態などで絞り込み検索が可能です。
• 📄 履歴書管理 - HeadHunter上の履歴書を閲覧・管理できます。
• ✉️ 求職申請 - カスタムの応募メッセージ付きで求人に応募できます。
• 🏢 企業情報取得 - 雇用主の詳細情報を取得できます。
• 📊 申請履歴追跡 - 求職申請の履歴を監視できます。
• 🤖 AI駆動エージェント - インテリジェントなマッチングによる自動求人検索が可能です。
• 🔐 OAuth 2.0 - HeadHunterによる安全な認証方式をサポートしています。

📦 インストール

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

💻 使用例

基本的な使用法

# モスクワでの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レポートを生成します。
• モスクワ地域に焦点を当てています。

使用方法:

Run vacancy-hunter agent

プロジェクト構造

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の資格情報

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。

📄 ライセンス

MITライセンス - 詳細は LICENSE ファイルを参照してください。

リンク

• HeadHunter APIのドキュメント
• Model Context Protocol
• Claude Codeのドキュメント

❤️ HeadHunterとMCPコミュニティのために作成されました