Bullhorn MCP Python

🚀 Bullhorn CRM MCP 服務器

這是一個基於 Python 的 模型上下文協議 (MCP) 服務器，它能讓 AI 助手使用自然語言查詢 Bullhorn CRM 數據。

支持的客戶端： Claude Desktop、Claude Code、Cursor、Windsurf、Cline、Continue、Zed 以及任何兼容 MCP 的客戶端。

這是付費連接器的開源替代方案，它可直接連接到 Bullhorn 的 REST API，無需額外訂閱。

由 Osher Digital 提供 - 專業的 AI 諮詢公司，助力企業利用人工智能的力量。

🚀 快速開始

本項目是一個 Python 服務器，藉助 MCP 協議，讓 AI 助手能以自然語言查詢 Bullhorn CRM 數據。以下是使用前的準備和操作步驟。

✨ 主要特性

• 直接 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 中的職位訂單。 參數：

示例：

list_jobs()                                    # 近期職位
list_jobs(query="isOpen:1")                   # 僅開放職位
list_jobs(query="title:Engineer", limit=10)  # 工程師職位
list_jobs(status="Accepting Candidates")      # 按狀態篩選

list_candidates

列出並篩選 Bullhorn CRM 中的候選人。 參數：

示例：

list_candidates()                              # 近期候選人
list_candidates(query="skillSet:Python")      # Python 開發者
list_candidates(status="Active", limit=50)    # 活躍候選人

get_job

獲取特定職位訂單的詳細信息。 參數：

get_candidate

獲取特定候選人的詳細信息。 參數：

search_entities

使用 Lucene 查詢語法搜索任何 Bullhorn 實體類型。 參數：

支持的實體：

• JobOrder - 職位發佈
• Candidate - 候選人/申請人
• Placement - 職位安排
• ClientCorporation - 客戶公司
• ClientContact - 客戶聯繫人
• JobSubmission - 候選人職位申請
• Appointment - 預定的約會
• Note - 筆記和評論
• 還有更多...

query_entities

使用類似 SQL 的 WHERE 語法查詢 Bullhorn 實體。 參數：

示例：

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 時，將返回以下字段：

環境變量

項目結構

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           # 配置管理

客戶端配置

此 MCP 服務器可與任何兼容 MCP 的客戶端配合使用。以下是流行客戶端的設置說明。

⚠️ 重要提示

在以下所有示例中，請將 /path/to/bullhorn-mcp-python 替換為您的實際安裝路徑。

Claude Desktop

添加到您的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

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

完全退出並重新打開 Claude Desktop 以使更改生效。

Claude Code (CLI)

使用 Claude Code CLI 添加服務器：

claude mcp add bullhorn \
  -e BULLHORN_CLIENT_ID=your_client_id \
  -e BULLHORN_CLIENT_SECRET=your_client_secret \
  -e BULLHORN_USERNAME=your_username \
  -e BULLHORN_PASSWORD=your_password \
  -- /path/to/bullhorn-mcp-python/.venv/bin/python -m bullhorn_mcp.server

或者添加到您的 ~/.claude/settings.json：

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

Cursor

添加到您的 Cursor MCP 配置：

• macOS：~/.cursor/mcp.json
• Windows：%USERPROFILE%\.cursor\mcp.json

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

重啟 Cursor 以使更改生效。

Windsurf (Codeium)

添加到您的 Windsurf MCP 配置：

• macOS：~/.codeium/windsurf/mcp_config.json
• Windows：%USERPROFILE%\.codeium\windsurf\mcp_config.json

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

重啟 Windsurf 以使更改生效。

VS Code with Cline Extension

添加到您的 Cline MCP 設置：

• macOS：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

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

VS Code with Continue Extension

添加到您的 Continue 配置文件 ~/.continue/config.json：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "/path/to/bullhorn-mcp-python/.venv/bin/python",
          "args": ["-m", "bullhorn_mcp.server"],
          "cwd": "/path/to/bullhorn-mcp-python"
        }
      }
    ]
  }
}

Zed Editor

添加到您的 Zed 設置文件 ~/.config/zed/settings.json：

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

🔧 技術細節

本項目使用 Python 實現，藉助 OAuth 2.0 協議連接到 Bullhorn 的 REST API。通過自動令牌管理，確保與 Bullhorn API 的穩定連接。同時，支持使用 Lucene 查詢和類似 SQL 的 WHERE 語法進行數據查詢，為用戶提供了靈活的數據檢索方式。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

致謝

• Bullhorn 提供的 REST API。
• Model Context Protocol 提供的 MCP 規範。
• Anthropic 提供的 Claude 和 MCP Python SDK。
• Cursor、Windsurf、Cline、Continue 和 Zed 團隊對 MCP 的支持。

關於 Osher Digital

本項目由 Osher Digital 維護，這是一家位於澳大利亞的專業 AI 諮詢公司。我們幫助企業集成 AI 解決方案，以簡化運營並推動增長。

需要 AI 集成幫助？ 聯繫我們

免責聲明

這是一個非官方、由社區維護的項目。它與 Bullhorn 沒有關聯，也未得到 Bullhorn 的官方維護或認可。