Loxo MCP Server

Loxo MCP Server

📚 ドキュメント： https://tbensonwest.github.io/loxo-mcp-server/

Claude が Loxo 採用プラットフォームに直接アクセスできるようにする Model Context Protocol（MCP）サーバーです。バージョン 1.7.0 では、候補者の検索と調査、求人パイプラインの管理、活動とコミュニケーションの追跡、企業とのやり取り、候補者記録の維持など、採用担当者のワークフロー全体をカバーする 34 個のツールを提供します。ツールの説明により、Claude は採用時のヒアリングメモや情報豊富な活動履歴を提示できます。そのため、情報を探し回らなくても、「この候補者とはどこまで話が進んでいましたか？」という質問に答えられます。

インストール

オプション 0：Smithery 経由でインストール（最も簡単）

Smithery 経由で Claude Desktop に自動インストールできます：

npx -y @smithery/cli install loxo-mcp-server --client claude

オプション 1：ローカルインストール

# Clone the repository
git clone [repository-url]
cd loxo-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

オプション 2：Docker インストール

# Clone the repository
git clone [repository-url]
cd loxo-mcp-server

# Build the Docker image
docker build -t loxo-mcp-server .

# Or use Docker Compose
docker-compose build

設定

用意されている .env.example ファイルを .env にコピーし、値を入力します：

cp .env.example .env

次に、.env ファイルを設定に合わせて更新します：

LOXO_API_KEY=your_api_key
LOXO_DOMAIN=app.loxo.co
LOXO_AGENCY_SLUG=your_agency_slug

必須の環境変数：

• LOXO_API_KEY：Loxo API キー
• LOXO_AGENCY_SLUG：Loxo における所属エージェンシーのスラッグ
• LOXO_DOMAIN：（任意）デフォルトは 'app.loxo.co'
• LOXO_DEFAULT_OWNER_ID：（任意）このサーバー経由で作成または更新した候補者の owned_by_id に設定する、デフォルトの Loxo ユーザー ID。loxo_list_users で ID を確認できます。設定されていない場合は担当者なしとなり、呼び出しごとに owned_by_id 引数で上書きできます。
• LOXO_DEFAULT_OWNER_EMAIL：（任意）案件の担当者に設定するデフォルトのメールアドレス。owner_email 引数が指定されていない場合に loxo_create_deal で使用されます。loxo_list_users でメールアドレスを確認できます。

Docker の設定

Docker を使用する場合、環境変数は Docker Compose 経由で .env ファイルから自動的に読み込まれます。または、直接渡すこともできます：

Docker Compose を使用する場合（推奨）：

# Ensure your .env file is configured
docker-compose up

Docker を直接使用する場合：

docker run -i \
  -e LOXO_API_KEY=your_api_key \
  -e LOXO_AGENCY_SLUG=your_agency_slug \
  -e LOXO_DOMAIN=app.loxo.co \
  loxo-mcp-server

注：MCP サーバーは stdin/stdout 経由で通信するため、-i フラグが必要です。

使用方法

サーバーの起動

ローカルの場合：

npm start

Docker Compose の場合：

docker-compose up

Docker を直接使用する場合：

docker run -i \
  -e LOXO_API_KEY=your_api_key \
  -e LOXO_AGENCY_SLUG=your_agency_slug \
  loxo-mcp-server

Claude Desktop との統合

Claude Desktop の設定（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します：

ローカルインストールの場合：

{
  "mcpServers": {
    "loxo": {
      "command": "node",
      "args": ["/path/to/loxo-mcp-server/build/index.js"],
      "env": {
        "LOXO_API_KEY": "your_api_key",
        "LOXO_AGENCY_SLUG": "your_agency_slug",
        "LOXO_DOMAIN": "app.loxo.co"
      }
    }
  }
}

Docker インストールの場合：

{
  "mcpServers": {
    "loxo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "LOXO_API_KEY=your_api_key",
        "-e", "LOXO_AGENCY_SLUG=your_agency_slug",
        "-e", "LOXO_DOMAIN=app.loxo.co",
        "loxo-mcp-server"
      ]
    }
  }
}

ワークフローの例

クライアント向けブリーフィング資料の準備

「Northvale の求人向けにブリーフィング資料を準備してください。」

1. loxo_search_jobs — Northvale の求人を検索して ID を取得します
2. loxo_get_job_pipeline — 候補者全員と現在のステージを取得します
3. loxo_get_candidate_brief（候補者ごと）— 1 回の呼び出しで、ヒアリングメモ、連絡先、情報豊富な最近の活動を取得します
4. 現在のステージ、志望理由、報酬の希望、最近の接点を含む、構成の整ったブリーフィング資料にまとめます

---

パイプラインの状況報告

「すべての進行中候補者について状況を報告してください。」

1. loxo_get_job_pipeline — その求人の候補者全員と各候補者のステージを取得します
2. loxo_get_candidate_brief（候補者ごと）— ヒアリングメモと最近の活動を取得し、それぞれのやり取りがどこまで進んでいるかをまとめます
3. ステージ、最終連絡日、次のステップを簡潔にまとめて報告します

---

新しい役職に候補者をマッチングする

「当社のデータベースに、この新しい CFO の役職に適した人はいますか？」

1. loxo_search_candidates — Lucene クエリを使用して、役職、スキル、業種、タグで検索します
2. loxo_get_candidate_brief（候補者を絞り込んだ後）— 面談時のメモと活動履歴を確認し、実際の適性と現在の就業可能状況を評価します
3. リクルーターのメモや最近の会話から得られた根拠を添えて、最適な候補者を提示します

利用可能なツール

候補者の検索と調査

• loxo_search_candidates — Lucene クエリを使用して候補者データベースを検索します。現在の役職、過去の勤務先、スキル、タグ、所在地、またはそれらの組み合わせで絞り込めます。スキルセットとタグを含む検索結果を1ページあたり100件返すため、追加の呼び出しをせずに絞り込めます。候補者を絞り込んだ後は、loxo_get_candidate_brief で詳細を確認してください。
• loxo_get_candidate — 経歴、現在の役職、スキル、タグ、報酬、リクルーターによる面談時のメモや通話メモ（description フィールド）を含む、候補者の完全なプロフィールを取得します。description フィールドは、候補者に関する情報の中でも特に詳しい内容が含まれることが多く、志望動機、個人的な事情、報酬の希望、役職の希望などを確認できます。
• loxo_get_candidate_brief — 候補者の詳しい情報が必要な場合に最適なツールです。プロフィール（面談時のメモを含む）、すべての連絡先情報、最近の重要な活動（通話、メール、メモ、面接など。パイプライン関連のノイズは除外）を1回の呼び出しで取得します。候補者への連絡文の作成、ブリーフィング資料の準備、候補者と役職の適性評価の前に使用してください。scroll_id によるページネーションに対応しており、さらに遡って過去の活動を確認できます。
• loxo_get_person_emails — 候補者について登録されているすべてのメールアドレスを、種別（勤務先、個人用など）とともに取得します。
• loxo_get_person_phones — 候補者について登録されているすべての電話番号を、種別（携帯電話、勤務先、自宅など）とともに取得します。
• loxo_list_person_job_profiles — 候補者の完全な職歴一覧を取得します。すべての役職、企業、在籍期間が含まれます。
• loxo_get_person_job_profile_detail — 候補者の職歴にある特定の役職の詳細情報を取得します。特定の職務の詳細な説明が必要な場合は、loxo_list_person_job_profiles の後に使用してください。
• loxo_list_person_education_profiles — 候補者の完全な学歴一覧を取得します。すべての学位、学校、在学期間が含まれます。
• loxo_get_person_education_profile_detail — 特定の学歴の詳細情報を取得します。特定の資格の詳しい情報が必要な場合は、loxo_list_person_education_profiles の後に使用してください。

パイプラインと求人の管理

• loxo_search_jobs — Lucene クエリ（役職、所在地、またはそれらの組み合わせ）を使用して募集中の役職を検索します。ページベースのページネーションを使用します。
• loxo_get_job — 仕事内容、応募要件、報酬、ステータス、採用チームを含む、求人の詳細を取得します。
• loxo_get_job_pipeline — 求人のパイプラインに現在登録されているすべての候補者と、各候補者のパイプライン段階（候補者発掘、スクリーニング、面接、内定、採用）を取得します。候補者 ID と段階を返します。各候補者の詳しい情報は、続けて loxo_get_candidate_brief で確認してください。
• loxo_add_to_pipeline — 候補者を求人のパイプラインに追加します。最初の段階に配置され、loxo_get_job_pipeline で確認できるようになります。

案件・BD パイプライン

• loxo_list_deal_workflows — ID と名前を含む、すべての案件ワークフロー（パイプライン）を一覧表示します。案件を検索または作成する前に、どのパイプラインがあるかを確認するために使用します。
• loxo_get_deal_workflow — パイプラインのステージを含む、案件ワークフローの詳細を取得します。loxo_create_deal で有効な pipeline_stage_id の値を確認するために使用します。
• loxo_search_deals — オプションの Lucene クエリと担当者のメールアドレスフィルターを使用して案件を検索します。scroll_id によるカーソルベースのページネーションを使用します。
• loxo_get_deal — 名前、金額、成約日、パイプラインのステージ、関連付けられた会社／人物／求人を含む、案件の詳細を取得します。
• loxo_create_deal — パイプラインに新しい案件を作成します。名前、金額、成約日、ワークフロー ID、パイプラインのステージ ID が必要です。担当者のメールアドレスが指定されていない場合は、LOXO_DEFAULT_OWNER_EMAIL が使用されます。
• loxo_log_deal_activity — 案件にアクティビティを記録します。案件固有のアクティビティタイプ ID を確認するには、案件の workflow_id を指定して loxo_get_activity_types を使用します。

アクティビティとコミュニケーションの追跡

• loxo_get_candidate_activities — 候補者の全アクティビティタイムラインを、最新のものから順に取得します。通話、メール、面談、メモ、パイプラインの移動、自動化イベントが含まれます。必要に応じて activity_type_ids で絞り込めます（ID の確認には loxo_get_activity_types を使用します）。要点を絞ったインテリジェンス重視の表示には、代わりに loxo_get_candidate_brief を使用します。
• loxo_log_activity — 候補者に対して完了したアクティビティ（通話、メール、面談、面接）を記録します。正しいアクティビティタイプ ID を確認するため、最初に loxo_get_activity_types を使用します。
• loxo_schedule_activity — 候補者の今後のアクティビティ（通話、面談、面接）を作成します。正しいアクティビティタイプ ID を確認するため、最初に loxo_get_activity_types を使用します。
• loxo_get_todays_tasks — 今日（または指定した日付範囲）の予定項目をすべて取得します。必要に応じてユーザーで絞り込めます。
• loxo_get_activity_types — すべてのアクティビティタイプとその ID を一覧表示します。候補者タイプの代わりに案件固有のアクティビティタイプを取得するには、必要に応じて workflow_id を指定します。アクティビティを記録またはスケジュールする前に呼び出してください。

会社と参照データ

• loxo_create_company — 新しい会社（クライアント／ターゲットアカウント）を作成します。現在は name のみを受け付けます。
• loxo_search_companies — Lucene クエリを使用して会社データベースを検索します。scroll_id によるカーソルベースのページネーションを使用します。
• loxo_get_company_details — 説明、連絡先、関係性、ステータスを含む、会社プロフィールの詳細を取得します。
• loxo_list_users — 名前とメールアドレスを含む、Loxo エージェンシーの全ユーザー（リクルーター、コーディネーターなど）を一覧表示します。タスクの絞り込みやレコードの所有者の確認に使用する user_id の値を探すために使用します。
• loxo_list_skillsets — すべてのスキルセットとセクター経験の選択肢を ID とともに一覧表示します。loxo_update_candidate の呼び出し前に、有効な skillset_ids と sector_ids の値を確認するために使用します。
• loxo_list_source_types — すべての候補者ソースタイプ（LinkedIn、API、紹介など）を ID とともに一覧表示します。有効な source_type_id の値を確認するために使用します。
• loxo_list_person_types — すべての人物タイプのカテゴリ（アクティブ候補者、見込み候補者など）を ID とともに一覧表示します。有効な person_type_id の値を確認するために使用します。

候補者管理

• loxo_create_candidate — 名前、連絡先情報、現在の役職を指定して、新しい候補者レコードを作成します。作成後、loxo_update_candidate を使用してタグ、スキルセット、人物タイプ、ソースタイプを設定します。
• loxo_update_candidate — 既存の候補者の詳細（プロフィール項目、タグ、スキルセット、セクター、人物タイプ、ソースタイプ）を更新します。最初に loxo_list_skillsets と loxo_list_person_types を使用して、有効な ID を確認します。
• loxo_upload_resume — CV または履歴書ファイルを候補者のプロフィールにアップロードします。Base64 でエンコードされたファイルの内容を受け付けます。ファイルは、候補者の Loxo レコードの「履歴書」セクションに表示されます。

アーキテクチャ

Model Context Protocol SDK 上に構築されており、stdio 経由で通信することで Claude Desktop および Claude.ai とシームレスに統合できます。

• v1.7.0 — 34 個のツールを搭載。ツールの説明により、Claude は採用候補者の受付メモ（description フィールド）や情報量の多い活動（通話、メール、メモ、面接）を提示し、パイプライン自動化のノイズを除外できます。
• すべての API 呼び出しは、Bearer トークン認証を使用して https://{LOXO_DOMAIN}/api/{LOXO_AGENCY_SLUG}/... に送信されます。
• POST/PATCH リクエストの本文には、ブラケット記法（例：person[name]）を使った application/x-www-form-urlencoded を使用します。
• すべてのエンドポイントは、公式の Loxo OpenAPI 仕様に照らして検証済みです。

ページネーション

エンドポイントに応じて、2 種類のページネーション方式を使用します。

• カーソルベース（scroll_id） — 候補者、企業、取引、スケジュール項目、活動で使用します。ページを順に取得するには、レスポンスの scroll_id を次のリクエストに渡します。
• ページベース（page / per_page） — 求人で使用します。page=1、page=2 などを渡します。

活動・イベントシステム

活動の追跡（通話、メール、ミーティング、メモ、パイプラインの移動）はすべて person_events API を介して行います。

• 予定された活動 — 将来の created_at 日時を指定して loxo_schedule_activity を使用します。
• 完了した活動 — loxo_log_activity を使用します。現在のタイムスタンプが自動的に適用されます。
• 活動は、人物、求人、企業のいずれか、または複数に関連付けることができます。
• loxo_get_candidate_brief は、情報量の多いタイプの活動のみを対象にフィルタリングします（パイプライン自動化イベントや、その他シグナルの弱い項目は除外します）。

開発

ローカル開発

# Run in development mode with watch mode
npm run dev

# Build the project
npm run build

# Start the server
npm start

Docker 開発

# Rebuild after code changes
docker-compose build

# Run with live logs
docker-compose up

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down