JinDaGe - bullhorn-mcp-python MCP Details

article

README

🚀 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 中的职位订单。 参数： | 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | 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           # 配置管理

客户端配置

此 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 的官方维护或认可。

bullhorn-mcp-python

README

🚀 Bullhorn CRM MCP 服务器

🚀 快速开始

✨ 主要特性

📦 安装指南

1. 克隆仓库

2. 安装依赖

3. 配置凭证

4. 测试连接

💻 使用示例

基础用法

高级用法

list_jobs

list_candidates

get_job

get_candidate

search_entities

query_entities

📚 详细文档

查询语法

Lucene 搜索语法

类似 SQL 的 WHERE 语法

默认字段

环境变量

项目结构

客户端配置

Claude Desktop

Claude Code (CLI)

Cursor

Windsurf (Codeium)

VS Code with Cline Extension

VS Code with Continue Extension

Zed Editor

🔧 技术细节

📄 许可证

致谢

关于 Osher Digital

免责声明

Runtime guide

Hosted runtime

Local runtime / other methods