Bullhorn MCP Python

Bullhorn CRM MCP服务器

蟒蛇 模型上下文协议（MCP） 服务器，使AI助手能够使用自然语言查询您的Bullhorn CRM数据。

适用于： Claude Desktop、Claude Code、Cursor、Windsurf、Cline、Continue、Zed和任何兼容MCP的客户端。

这是付费连接器的开源替代方案-它直接连接到Bullhorn的REST API，无需额外订阅。

给你带来的 奥舍尔数字 -专业的人工智能顾问帮助企业利用人工智能的力量。

特性

• 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数据的风险

先决条件

• Python 3.10+
• 紫外线 （推荐）或pip
• 具有API访问权限的Bullhorn CRM帐户
• Bullhorn API凭据（客户端ID、客户端机密、用户名、密码）

获取您的Bullhorn API证书

你需要从Bullhorn获得四份证书：

1. 客户端ID 和 客户端密钥 -OAuth应用程序凭据
2. API用户名 和 API密码 -API访问的服务帐户

要获得这些：

1. 联系您的Bullhorn管理员或客户经理
2. 请求您的帐户访问API
3. 他们将为您提供OAuth客户端凭据
4. 创建或使用现有服务帐户进行API身份验证

备注：您的API用户名/密码可能与您的常规Bullhorn登录凭据不同。

安装

1.克隆存储库

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

2.安装依赖项

使用紫外线（推荐）：

uv venv && uv pip install -e .

或者使用pip：

python -m venv .venv
source .venv/bin/activate  # On 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'Successfully connected! Found {len(jobs)} jobs.')
"

客户端配置

此MCP服务器可与任何兼容MCP的客户端配合使用。以下是常见客户端的设置说明。

备注：替换 /path/to/bullhorn-mcp-python 在下面的所有示例中使用您的实际安装路径。

______________________________________________________________________

克劳德桌面版

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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（完全退出并重新打开）以使更改生效。

______________________________________________________________________

克劳德代码（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"
    }
  }
}

______________________________________________________________________

光标

添加到光标MCP配置中：

macOS: ~/.cursor/mcp.json 视窗: %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以使更改生效。

______________________________________________________________________

风帆冲浪（Codeium）

添加到您的Windsurf MCP配置中：

macOS: ~/.codeium/windsurf/mcp_config.json 视窗: %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以使更改生效。

______________________________________________________________________

带有Cline扩展的VS代码

添加到您的Cline MCP设置中：

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 视窗: %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"
    }
  }
}

______________________________________________________________________

带有Continue扩展名的VS代码

添加到您的继续配置 ~/.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编辑

添加到您的Zed设置 ~/.config/zed/settings.json:

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

______________________________________________________________________

查询示例

配置后，您可以就Bullhorn数据提出自然语言问题：

• “列出最近10个空缺职位”
• “寻找有Python经验的候选人”
• “显示作业#12345的详细信息”
• “搜索本月添加的活跃候选人”
• “上周做了什么安排？”

工具参考

list_jobs

从Bullhorn CRM中列出并筛选工作订单。

参数：

示例：

list_jobs()                                    # Recent jobs
list_jobs(query="isOpen:1")                   # Open jobs only
list_jobs(query="title:Engineer", limit=10)  # Engineer jobs
list_jobs(status="Accepting Candidates")      # By status

list_candidates

从Bullhorn CRM中列出并筛选候选人。

参数：

示例：

list_candidates()                              # Recent candidates
list_candidates(query="skillSet:Python")      # Python developers
list_candidates(status="Active", limit=50)    # Active candidates

get_job

获取特定工单的详细信息。

参数：

get_candidate

获取特定候选人的详细信息。

参数：

search_entities

使用Lucene查询语法搜索任何Bullhorn实体类型。

参数：

支持的实体：

• JobOrder -招聘信息
• Candidate -候选人/申请人
• Placement -工作安排
• ClientCorporation -客户公司
• ClientContact -客户联系人
• JobSubmission -候选人提交工作
• Appointment -预约时间
• Note -注释和评论
• 还有更多。..

查询项

使用类似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                           # Field contains value
isOpen:1                                 # Boolean/numeric field
salary:[50000 TO 100000]                # Range query
firstName:"John"                         # Exact phrase
firstName:John AND lastName:Smith       # AND condition
status:Active OR status:Available       # OR condition
NOT status:Inactive                      # Negation
name:Acme*                              # Wildcard

类似SQL的WHERE语法

由...使用 query_entities:

salary > 100000                          # Comparison
status = 'Active'                        # Equality (use single quotes)
dateAdded > '2024-01-01'                # Date comparison
id IN (1, 2, 3, 4, 5)                   # IN clause
firstName = 'John' AND salary > 50000   # AND condition

备注：Bullhorn的查询端点不支持LIKE运算符。

默认字段

当 fields 如果未指定，则返回以下字段：

工作订单： id, title, status, employmentType, dateAdded, startDate, salary, clientCorporation, owner, description, numOpenings, isOpen

候选人： id, firstName, lastName, email, phone, status, dateAdded, occupation, skillSet, owner

环境变量

项目结构

bullhorn-mcp-python/
├── pyproject.toml              # Project configuration and dependencies
├── .env.example                # Environment variables template
├── README.md                   # This file
├── LICENSE                     # MIT License
└── src/
    └── bullhorn_mcp/
        ├── __init__.py         # Package initialization
        ├── server.py           # MCP server with tool definitions
        ├── auth.py             # Bullhorn OAuth 2.0 authentication
        ├── client.py           # Bullhorn REST API client
        └── config.py           # Configuration management

故障排除

“缺少必需的环境变量”

确保在您的 .env 文件或环境。

身份验证错误

1. 验证您的凭据是否正确
2. 检查您的API用户是否具有适当的权限
3. 确保您的Bullhorn帐户已启用API访问

“连接被拒绝”或超时错误

1. 检查您的互联网连接
2. 验证Bullhorn数据中心的身份验证/登录URL是否正确
3. 一些Bullhorn实例使用区域URL（例如。， rest9.bullhornstaffing.com)

MCP服务器未出现在您的客户端中

1. 确保客户端的配置文件路径正确（请参阅客户端配置部分）
2. 验证配置中的Python路径是否指向 .venv 目录
3. 完全退出并重新启动客户端应用程序
4. 检查客户日志中的错误消息
5. 手动测试服务器：

   cd /path/to/bullhorn-mcp-python
   .venv/bin/python -m bullhorn_mcp.server

服务器应无错误启动（它将等待stdin上的输入）

贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 扩音器 用于他们的REST API
• 模型上下文协议 对于MCP规范
• Anthropic Claude和MCP Python SDK

______________________________________________________________________

关于奥舍数码

该项目由以下人员维护 奥舍尔数字，澳大利亚的专业人工智能顾问。我们帮助企业整合人工智能解决方案，以简化运营并推动增长。

需要人工智能集成方面的帮助吗？ 联系

免责声明

这是一个非官方的、由社区维护的项目。它与Bullhorn没有附属关系，也没有官方维护或认可。