Bullhorn MCP Python

顧客データプラットフォーム開発者ツール .Python

スコア : 2ポイント

ダウンロード数 : 6.8K

更新時間 : 2026-03-13

サイトを開く

インストール

以下のコマンドをクライアントにコピーして設定

{
  "mcpServers": {
    "bullhorn": {
      "command": "/path/to/bullhorn-mcp-python/.venv/bin/python",
      "args": ["-m", "bullhorn_mcp.server"],
      "cwd": "/path/to/bullhorn-mcp-python"
    }
  }
}

注意：あなたのキーは機密情報です。誰とも共有しないでください。

🚀 Bullhorn CRM MCP Server

このPython製のModel Context Protocol (MCP)サーバーは、AIアシスタントが自然言語を使ってBullhorn CRMのデータを照会できるようにします。

対応クライアント: Claude Desktop、Claude Code、Cursor、Windsurf、Cline、Continue、Zed、およびMCP互換の任意のクライアント。

これは有料コネクタのオープンソースな代替手段で、追加のサブスクリプションを必要とせずにBullhornのREST APIに直接接続します。

提供: Osher Digital - 企業が人工知能の力を活用できるよう支援するAI専門コンサルタント。

✨ 主な機能

直接APIアクセス - OAuth 2.0を使用してBullhornのREST APIに接続します。
自然言語クエリ - 「最後の10件のオープンな求人を表示して」のような質問を行えます。
6つの強力なツール:
- list_jobs - 求人を一覧表示し、フィルタリングします。
- list_candidates - 候補者を一覧表示し、フィルタリングします。
- get_job - IDで詳細な求人情報を取得します。
- get_candidate - IDで詳細な候補者情報を取得します。
- search_entities - Luceneクエリで任意のBullhornエンティティを検索します。
- query_entities - SQLのWHERE構文でエンティティを照会します。
自動トークン管理 - OAuthトークンの更新を自動的に処理します。
読み取り専用アクセス - 安全に使用でき、CRMデータを変更するリスクはありません。

📦 インストール

1. リポジトリをクローンする

git clone https://github.com/osherai/bullhorn-mcp-python.git
cd bullhorn-mcp-python

2. 依存関係をインストールする

uvを使用する場合（推奨）:

uv venv && uv pip install -e .

またはpipを使用する場合:

python -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate
pip install -e .

3. 認証情報を設定する

サンプルの環境ファイルをコピーし、認証情報を追加します。

cp .env.example .env

.envを編集し、Bullhorn APIの認証情報を追加します。

BULLHORN_CLIENT_ID=your_client_id
BULLHORN_CLIENT_SECRET=your_client_secret
BULLHORN_USERNAME=your_api_username
BULLHORN_PASSWORD=your_api_password

4. 接続をテストする

.venv/bin/python -c "
from bullhorn_mcp.config import BullhornConfig
from bullhorn_mcp.auth import BullhornAuth
from bullhorn_mcp.client import BullhornClient

config = BullhornConfig.from_env()
auth = BullhornAuth(config)
client = BullhornClient(auth)

jobs = client.search('JobOrder', 'isDeleted:0', count=3)
print(f'接続に成功しました！ {len(jobs)} 件の求人が見つかりました。')
"

💻 使用例

基本的な使用法

設定が完了すると、Bullhornのデータに関する自然言語の質問を行うことができます。

"最後の10件のオープンな求人を表示して"
"Pythonの経験がある候補者を探す"
"求人番号 #12345 の詳細を表示して"
"今月追加されたアクティブな候補者を検索する"
"先週行われた配置はどれですか？"

📚 詳細ドキュメント

ツールリファレンス

list_jobs

Bullhorn CRMから求人を一覧表示し、フィルタリングします。

パラメータ:

パラメータ	型	必須	説明
`query`	文字列	いいえ	Lucene検索クエリ
`status`	文字列	いいえ	求人ステータスでフィルタリング
`limit`	整数	いいえ	最大結果数 (デフォルト: 20, 最大: 500)
`fields`	文字列	いいえ	返すフィールドをカンマ区切りで指定

使用例:

list_jobs()                                    # 最近の求人
list_jobs(query="isOpen:1")                   # オープンな求人のみ
list_jobs(query="title:Engineer", limit=10)  # エンジニアの求人
list_jobs(status="Accepting Candidates")      # ステータスで絞り込み

list_candidates

Bullhorn CRMから候補者を一覧表示し、フィルタリングします。

パラメータ:

パラメータ	型	必須	説明
`query`	文字列	いいえ	Lucene検索クエリ
`status`	文字列	いいえ	候補者ステータスでフィルタリング
`limit`	整数	いいえ	最大結果数 (デフォルト: 20, 最大: 500)
`fields`	文字列	いいえ	返すフィールドをカンマ区切りで指定

使用例:

list_candidates()                              # 最近の候補者
list_candidates(query="skillSet:Python")      # Python開発者
list_candidates(status="Active", limit=50)    # アクティブな候補者

get_job

特定の求人の詳細情報を取得します。

パラメータ:

パラメータ	型	必須	説明
`job_id`	整数	はい	求人ID
`fields`	文字列	いいえ	返すフィールドをカンマ区切りで指定

get_candidate

特定の候補者の詳細情報を取得します。

パラメータ:

パラメータ	型	必須	説明
`candidate_id`	整数	はい	候補者ID
`fields`	文字列	いいえ	返すフィールドをカンマ区切りで指定

search_entities

Luceneクエリ構文を使用して、任意のBullhornエンティティタイプを検索します。

パラメータ:

パラメータ	型	必須	説明
`entity`	文字列	はい	エンティティタイプ (JobOrder、Candidate、Placementなど)
`query`	文字列	はい	Lucene検索クエリ
`limit`	整数	いいえ	最大結果数 (デフォルト: 20, 最大: 500)
`fields`	文字列	いいえ	返すフィールドをカンマ区切りで指定

サポートされるエンティティ:

JobOrder - 求人
Candidate - 候補者/応募者
Placement - 求人配置
ClientCorporation - クライアント企業
ClientContact - クライアント連絡先
JobSubmission - 求人への候補者提出
Appointment - 予定された予約
Note - メモとコメント
その他多数...

query_entities

SQLのWHERE構文を使用してBullhornエンティティを照会します。

パラメータ:

パラメータ	型	必須	説明
`entity`	文字列	はい	エンティティタイプ
`where`	文字列	はい	WHERE句
`limit`	整数	いいえ	最大結果数 (デフォルト: 20, 最大: 500)
`fields`	文字列	いいえ	返すフィールドをカンマ区切りで指定
`order_by`	文字列	いいえ	並び順 (例: "-dateAdded")

使用例:

query_entities(entity="JobOrder", where="salary > 100000")
query_entities(entity="Candidate", where="status='Active'", order_by="-dateAdded")

クエリ構文

Lucene検索構文

list_jobs、list_candidates、search_entitiesで使用されます。

title:Engineer                           # フィールドに値が含まれる
isOpen:1                                 # ブール型/数値型のフィールド
salary:[50000 TO 100000]                # 範囲クエリ
firstName:"John"                         # 正確なフレーズ
firstName:John AND lastName:Smith       # AND条件
status:Active OR status:Available       # OR条件
NOT status:Inactive                      # 否定
name:Acme*                              # ワイルドカード

SQLのWHERE構文

query_entitiesで使用されます。

salary > 100000                          # 比較
status = 'Active'                        # 等価 (シングルクォートを使用)
dateAdded > '2024-01-01'                # 日付比較
id IN (1, 2, 3, 4, 5)                   # IN句
firstName = 'John' AND salary > 50000   # AND条件

⚠️ 重要提示

BullhornのクエリエンドポイントではLIKE演算子はサポートされていません。

デフォルトのフィールド

fieldsが指定されない場合、以下のフィールドが返されます。

JobOrder: id, title, status, employmentType, dateAdded, startDate, salary, clientCorporation, owner, description, numOpenings, isOpen

Candidate: id, firstName, lastName, email, phone, status, dateAdded, occupation, skillSet, owner

環境変数

変数	必須	説明
`BULLHORN_CLIENT_ID`	はい	OAuth 2.0のクライアントID
`BULLHORN_CLIENT_SECRET`	はい	OAuth 2.0のクライアントシークレット
`BULLHORN_USERNAME`	はい	APIユーザー名
`BULLHORN_PASSWORD`	はい	APIパスワード
`BULLHORN_AUTH_URL`	いいえ	認証URL (デフォルト: https://auth.bullhornstaffing.com)
`BULLHORN_LOGIN_URL`	いいえ	ログインURL (デフォルト: https://rest.bullhornstaffing.com)

プロジェクト構造

bullhorn-mcp-python/
├── pyproject.toml              # プロジェクト構成と依存関係
├── .env.example                # 環境変数のテンプレート
├── README.md                   # このファイル
├── LICENSE                     # MITライセンス
└── src/
    └── bullhorn_mcp/
        ├── __init__.py         # パッケージの初期化
        ├── server.py           # ツール定義付きのMCPサーバー
        ├── auth.py             # Bullhorn OAuth 2.0認証
        ├── client.py           # Bullhorn REST APIクライアント
        └── config.py           # 構成管理

トラブルシューティング

"Missing required environment variables"

.envファイルまたは環境にすべての必須変数が設定されていることを確認してください。

認証エラー

認証情報が正しいことを確認してください。
APIユーザーに適切な権限があることを確認してください。
BullhornアカウントでAPIアクセスが有効になっていることを確認してください。

"Connection refused" またはタイムアウトエラー

インターネット接続を確認してください。
認証/ログインURLがBullhornのデータセンターに適していることを確認してください。
一部のBullhornインスタンスでは、地域固有のURL (例: rest9.bullhornstaffing.com) を使用しています。

MCPサーバーがクライアントに表示されない場合

クライアントの設定ファイルのパスが正しいことを確認してください（クライアント構成セクションを参照）。
設定内のPythonのパスが.venvディレクトリを指していることを確認してください。
クライアントアプリケーションを完全に終了し、再起動してください。
クライアントのログを確認して、エラーメッセージを確認してください。
サーバーを手動でテストしてください。
```
cd /path/to/bullhorn-mcp-python
.venv/bin/python -m bullhorn_mcp.server
```
サーバーはエラーなしで起動するはずです（標準入力を待機します）。