Bullhorn CRM MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Bullhorn CRM MCP Server Show me the last 10 open job orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Bullhorn CRM MCP Server
A Python Model Context Protocol (MCP) server that enables AI assistants to query your Bullhorn CRM data using natural language.
Works with: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Zed, and any MCP-compatible client.
This is an open-source alternative to paid connectors - it connects directly to Bullhorn's REST API with no additional subscriptions required.
Brought to you by Osher Digital - Specialist AI consultants helping businesses harness the power of artificial intelligence.
Features
Direct API Access - Connects to Bullhorn's REST API using OAuth 2.0
Natural Language Queries - Ask questions like "Show me the last 10 open jobs"
6 Powerful Tools:
list_jobs- List and filter job orderslist_candidates- List and filter candidatesget_job- Get detailed job information by IDget_candidate- Get detailed candidate information by IDsearch_entities- Search any Bullhorn entity with Lucene queriesquery_entities- Query entities with SQL-like WHERE syntax
Automatic Token Management - Handles OAuth token refresh automatically
Read-Only Access - Safe to use, no risk of modifying your CRM data
Related MCP server: Zoho CRM MCP Server
Prerequisites
Python 3.10+
uv (recommended) or pip
Bullhorn CRM account with API access
Bullhorn API credentials (Client ID, Client Secret, Username, Password)
Getting Your Bullhorn API Credentials
You'll need four credentials from Bullhorn:
Client ID and Client Secret - OAuth application credentials
API Username and API Password - Service account for API access
To obtain these:
Contact your Bullhorn administrator or account manager
Request API access for your account
They will provide you with OAuth client credentials
Create or use an existing service account for API authentication
Note: Your API username/password may be different from your regular Bullhorn login credentials.
Installation
1. Clone the Repository
git clone https://github.com/osherai/bullhorn-mcp-python.git
cd bullhorn-mcp-python2. Install Dependencies
Using uv (recommended):
uv venv && uv pip install -e .Or using pip:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .3. Configure Credentials
Copy the example environment file and add your credentials:
cp .env.example .envEdit .env with your Bullhorn API credentials:
BULLHORN_CLIENT_ID=your_client_id
BULLHORN_CLIENT_SECRET=your_client_secret
BULLHORN_USERNAME=your_api_username
BULLHORN_PASSWORD=your_api_password4. Test the Connection
.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.')
"Client Configuration
This MCP server works with any MCP-compatible client. Below are setup instructions for popular clients.
Note: Replace
/path/to/bullhorn-mcp-pythonwith your actual installation path in all examples below.
Claude Desktop
Add to your Claude Desktop configuration file:
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"
}
}
}Restart Claude Desktop (fully quit and reopen) for changes to take effect.
Claude Code (CLI)
Add the server using the 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.serverOr add to your ~/.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
Add to your Cursor MCP configuration:
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"
}
}
}Restart Cursor for changes to take effect.
Windsurf (Codeium)
Add to your Windsurf MCP configuration:
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"
}
}
}Restart Windsurf for changes to take effect.
VS Code with Cline Extension
Add to your Cline MCP settings:
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
Add to your Continue configuration at ~/.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
Add to your Zed settings at ~/.config/zed/settings.json:
{
"context_servers": {
"bullhorn": {
"command": {
"path": "/path/to/bullhorn-mcp-python/.venv/bin/python",
"args": ["-m", "bullhorn_mcp.server"]
},
"settings": {}
}
}
}Example Queries
Once configured, you can ask natural language questions about your Bullhorn data:
"List the last 10 open jobs"
"Find candidates with Python experience"
"Show me details for job #12345"
"Search for active candidates added this month"
"What placements were made last week?"
Tools Reference
list_jobs
List and filter job orders from Bullhorn CRM.
Parameters:
Parameter | Type | Required | Description |
| string | No | Lucene search query |
| string | No | Filter by job status |
| integer | No | Max results (default: 20, max: 500) |
| string | No | Comma-separated fields to return |
Examples:
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 statuslist_candidates
List and filter candidates from Bullhorn CRM.
Parameters:
Parameter | Type | Required | Description |
| string | No | Lucene search query |
| string | No | Filter by candidate status |
| integer | No | Max results (default: 20, max: 500) |
| string | No | Comma-separated fields to return |
Examples:
list_candidates() # Recent candidates
list_candidates(query="skillSet:Python") # Python developers
list_candidates(status="Active", limit=50) # Active candidatesget_job
Get detailed information for a specific job order.
Parameters:
Parameter | Type | Required | Description |
| integer | Yes | The JobOrder ID |
| string | No | Comma-separated fields to return |
get_candidate
Get detailed information for a specific candidate.
Parameters:
Parameter | Type | Required | Description |
| integer | Yes | The Candidate ID |
| string | No | Comma-separated fields to return |
search_entities
Search any Bullhorn entity type using Lucene query syntax.
Parameters:
Parameter | Type | Required | Description |
| string | Yes | Entity type (JobOrder, Candidate, Placement, etc.) |
| string | Yes | Lucene search query |
| integer | No | Max results (default: 20, max: 500) |
| string | No | Comma-separated fields to return |
Supported Entities:
JobOrder- Job postingsCandidate- Candidates/applicantsPlacement- Job placementsClientCorporation- Client companiesClientContact- Client contactsJobSubmission- Candidate submissions to jobsAppointment- Scheduled appointmentsNote- Notes and commentsAnd many more...
query_entities
Query Bullhorn entities using SQL-like WHERE syntax.
Parameters:
Parameter | Type | Required | Description |
| string | Yes | Entity type |
| string | Yes | WHERE clause |
| integer | No | Max results (default: 20, max: 500) |
| string | No | Comma-separated fields to return |
| string | No | Sort order (e.g., "-dateAdded") |
Examples:
query_entities(entity="JobOrder", where="salary > 100000")
query_entities(entity="Candidate", where="status='Active'", order_by="-dateAdded")Query Syntax
Lucene Search Syntax
Used by list_jobs, list_candidates, and 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* # WildcardSQL-like WHERE Syntax
Used by 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 conditionNote: The LIKE operator is not supported in Bullhorn's query endpoint.
Default Fields
When fields is not specified, the following fields are returned:
JobOrder:
id, title, status, employmentType, dateAdded, startDate, salary, clientCorporation, owner, description, numOpenings, isOpen
Candidate:
id, firstName, lastName, email, phone, status, dateAdded, occupation, skillSet, owner
Environment Variables
Variable | Required | Description |
| Yes | OAuth 2.0 Client ID |
| Yes | OAuth 2.0 Client Secret |
| Yes | API Username |
| Yes | API Password |
| No | Auth URL (default: https://auth.bullhornstaffing.com) |
| No | Login URL (default: https://rest.bullhornstaffing.com) |
Project Structure
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 managementTroubleshooting
"Missing required environment variables"
Ensure all required variables are set in your .env file or environment.
Authentication Errors
Verify your credentials are correct
Check that your API user has appropriate permissions
Ensure your Bullhorn account has API access enabled
"Connection refused" or timeout errors
Check your internet connection
Verify the auth/login URLs are correct for your Bullhorn datacenter
Some Bullhorn instances use regional URLs (e.g.,
rest9.bullhornstaffing.com)
MCP server not appearing in your client
Ensure the config file path is correct for your client (see Client Configuration section)
Verify the Python path in the config points to the
.venvdirectoryFully quit and restart your client application
Check your client's logs for error messages
Test the server manually:
cd /path/to/bullhorn-mcp-python .venv/bin/python -m bullhorn_mcp.serverThe server should start without errors (it will wait for input on stdin)
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
Bullhorn for their REST API
Model Context Protocol for the MCP specification
Anthropic for Claude and the MCP Python SDK
The teams behind Cursor, Windsurf, Cline, Continue, and Zed for MCP support
About Osher Digital
This project is maintained by Osher Digital, specialist AI consultants based in Australia. We help businesses integrate AI solutions to streamline operations and drive growth.
Need help with AI integration? Get in touch
Disclaimer
This is an unofficial, community-maintained project. It is not affiliated with, officially maintained, or endorsed by Bullhorn.
Available Tools
6 toolsget_candidateA
Get details for a specific candidate by ID.
Args: candidate_id: The Candidate ID fields: Comma-separated fields to return (default: all common fields)
Returns: JSON object with candidate details
Inputs: candidate_id (required), fields. Returns: result
get_jobA
Get details for a specific job order by ID.
Args: job_id: The JobOrder ID fields: Comma-separated fields to return (default: all common fields)
Returns: JSON object with job details
Inputs: job_id (required), fields. Returns: result
list_candidatesA
List and filter candidates from Bullhorn CRM.
Args: query: Lucene search query (e.g., "lastName:Smith" or "skillSet:Python") status: Filter by candidate status limit: Maximum number of results (1-500, default 20) fields: Comma-separated fields to return
Returns: JSON array of candidates
Examples: - list_candidates() - Get recent candidates - list_candidates(query="skillSet:Python") - Find Python developers - list_candidates(query="lastName:Smith AND status:Active") - list_candidates(status="Active", limit=50)
Inputs: query, status, limit, fields. Returns: result
list_jobsA
List and filter job orders from Bullhorn CRM.
Args: query: Lucene search query (e.g., "title:Engineer AND isOpen:1") status: Filter by job status limit: Maximum number of results (1-500, default 20) fields: Comma-separated fields to return
Returns: JSON array of job orders
Examples: - list_jobs() - Get recent jobs - list_jobs(query="isOpen:1") - Get open jobs - list_jobs(query="title:Software AND employmentType:Direct Hire", limit=10) - list_jobs(status="Accepting Candidates")
Inputs: query, status, limit, fields. Returns: result
query_entitiesA
Query Bullhorn entities using SQL-like WHERE syntax.
Args: entity: Entity type (JobOrder, Candidate, etc.) where: WHERE clause (e.g., "salary > 100000 AND status='Active'") limit: Maximum number of results (1-500, default 20) fields: Comma-separated fields to return order_by: Sort order (e.g., "-dateAdded" for newest first)
Returns: JSON array of matching entities
Examples: - query_entities(entity="JobOrder", where="salary > 100000") - query_entities(entity="Candidate", where="status='Active'", order_by="-dateAdded")
Inputs: entity (required), where (required), limit, fields, +1 more. Returns: result
search_entitiesA
Search any Bullhorn entity type using Lucene query syntax.
Args: entity: Entity type (JobOrder, Candidate, Placement, ClientCorporation, ClientContact, etc.) query: Lucene search query limit: Maximum number of results (1-500, default 20) fields: Comma-separated fields to return
Returns: JSON array of matching entities
Examples: - search_entities(entity="Placement", query="status:Approved") - search_entities(entity="ClientCorporation", query="name:Acme*") - search_entities(entity="JobSubmission", query="jobOrder.id:12345")
Inputs: entity (required), query (required), limit, fields. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tool purposes are mostly distinct, but list_candidates/list_jobs overlap with search_entities since search_entities can also query candidates/jobs with Lucene syntax, creating potential confusion for an agent.
Names follow a verb_noun pattern (get_, list_, query_, search_), but verbs are not uniform (get vs list, query vs search). This is a minor inconsistency.
Six tools is appropriate for a read-only CRM data access layer. Each tool has a clear purpose without unnecessary bloat.
The server covers only read operations (get, list, query, search) and provides no create, update, or delete tools. For a CRM server, this is a significant gap that will limit agent workflows.
Maintenance
Related MCP Connectors
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Web search, data extraction and controlled browser automation for AI assistants via OAuth.
Connect AI assistants to JustRoadmap to list, read and update workspaces, roadmaps, lanes and items. OAuth sign-in with read-only or read-and-change access per workspace. No delete tools.
Related MCP Servers
- FlicenseAqualityNot gradedmaintenanceEnables AI assistants to interact with HaloPSA data through secure OAuth2 authentication. Supports SQL queries against the HaloPSA database, API endpoint exploration, and direct API calls for comprehensive PSA data analysis and management.107 npm-
- AlicenseNot gradedqualityDmaintenanceEnables read-only interaction with Zoho CRM data through natural language queries, allowing users to search records, list modules, retrieve field information, and count records using secure OAuth authentication.2ISC
- AlicenseAqualityDmaintenanceEnables AI assistants to securely interact with Salesforce CRM data through SOQL queries, CRUD operations, and metadata exploration. Supports connecting to Salesforce objects like Accounts, Contacts, and Opportunities via OAuth 2.0 authentication.82MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Salesforce CRM by executing SOQL queries and performing CRUD operations on records such as Leads. It supports secure OAuth 2.0 authentication and provides management for both standard and custom Salesforce fields.-