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 orders
- list_candidates - List and filter candidates
- get_job - Get detailed job information by ID
- get_candidate - Get detailed candidate information by ID
- search_entities - Search any Bullhorn entity with Lucene queries
- query_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

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-python

2. 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 .env

Edit .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_password

4. 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-python with 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.server

Or 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 | |-----------|------|----------|-------------| | query | string | No | Lucene search query | | status | string | No | Filter by job status | | limit | integer | No | Max results (default: 20, max: 500) | | fields | 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 status

list_candidates

List and filter candidates from Bullhorn CRM.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | No | Lucene search query | | status | string | No | Filter by candidate status | | limit | integer | No | Max results (default: 20, max: 500) | | fields | 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 candidates

get_job

Get detailed information for a specific job order.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | job_id | integer | Yes | The JobOrder ID | | fields | string | No | Comma-separated fields to return |

get_candidate

Get detailed information for a specific candidate.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | candidate_id | integer | Yes | The Candidate ID | | fields | string | No | Comma-separated fields to return |

search_entities

Search any Bullhorn entity type using Lucene query syntax.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | entity | string | Yes | Entity type (JobOrder, Candidate, Placement, etc.) | | query | string | Yes | Lucene search query | | limit | integer | No | Max results (default: 20, max: 500) | | fields | string | No | Comma-separated fields to return |

Supported Entities:

JobOrder - Job postings
Candidate - Candidates/applicants
Placement - Job placements
ClientCorporation - Client companies
ClientContact - Client contacts
JobSubmission - Candidate submissions to jobs
Appointment - Scheduled appointments
Note - Notes and comments
And many more...

query_entities

Query Bullhorn entities using SQL-like WHERE syntax.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | entity | string | Yes | Entity type | | where | string | Yes | WHERE clause | | limit | integer | No | Max results (default: 20, max: 500) | | fields | string | No | Comma-separated fields to return | | order_by | 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*                              # Wildcard

SQL-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 condition

Note: 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 | |----------|----------|-------------| | BULLHORN_CLIENT_ID | Yes | OAuth 2.0 Client ID | | BULLHORN_CLIENT_SECRET | Yes | OAuth 2.0 Client Secret | | BULLHORN_USERNAME | Yes | API Username | | BULLHORN_PASSWORD | Yes | API Password | | BULLHORN_AUTH_URL | No | Auth URL (default: https://auth.bullhornstaffing.com) | | BULLHORN_LOGIN_URL | 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 management

Troubleshooting

"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 .venv directory
Fully 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.server
```
The 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.

Bullhorn CRM MCP Server

Features

Prerequisites

Getting Your Bullhorn API Credentials

Installation

1. Clone the Repository

2. Install Dependencies

3. Configure Credentials

4. Test the Connection

Client Configuration

Claude Desktop

Claude Code (CLI)

Cursor

Windsurf (Codeium)

VS Code with Cline Extension

VS Code with Continue Extension

Zed Editor

Example Queries

Tools Reference

list_jobs

list_candidates

get_job

get_candidate

search_entities

query_entities

Query Syntax

Lucene Search Syntax

SQL-like WHERE Syntax

Default Fields

Environment Variables

Project Structure

Troubleshooting

"Missing required environment variables"

Authentication Errors

"Connection refused" or timeout errors

MCP server not appearing in your client

Contributing

License

Acknowledgments

About Osher Digital

Disclaimer

安装包 （如果需要）

Cursor 配置 (mcp.json)

安装包（如果需要）