Bullhorn MCP Python

🚀 Bullhorn CRM MCP Server

This is a Python Model Context Protocol (MCP) server that allows AI assistants to query your Bullhorn CRM data using natural language.

Compatible with: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Zed, and any MCP-compatible client.

It serves as an open - source alternative to paid connectors, directly connecting to Bullhorn's REST API without the need for additional subscriptions.

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: You can 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, with no risk of modifying your CRM data.

📦 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.')
"

💻 Usage Examples

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:

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:

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:

get_candidate

Get detailed information for a specific candidate.

Parameters:

search_entities

Search any Bullhorn entity type using Lucene query syntax.

Parameters:

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:

Examples:

query_entities(entity="JobOrder", where="salary > 100000")
query_entities(entity="Candidate", where="status='Active'", order_by="-dateAdded")

📚 Documentation

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

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

🔧 Technical Details

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:

1. Client ID and Client Secret - OAuth application credentials
2. API Username and API Password - Service account for API access

To obtain these:

1. Contact your Bullhorn administrator or account manager.
2. Request API access for your account.
3. They will provide you with OAuth client credentials.
4. Create or use an existing service account for API authentication.

Note: Your API username/password may be different from your regular Bullhorn login credentials.

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": {}
    }
  }
}

Troubleshooting

"Missing required environment variables"

Ensure all required variables are set in your .env file or environment.

Authentication Errors

1. Verify your credentials are correct.
2. Check that your API user has appropriate permissions.
3. Ensure your Bullhorn account has API access enabled.

"Connection refused" or timeout errors

1. Check your internet connection.
2. Verify the auth/login URLs are correct for your Bullhorn datacenter.
3. Some Bullhorn instances use regional URLs (e.g., rest9.bullhornstaffing.com).

MCP server not appearing in your client

1. Ensure the config file path is correct for your client (see Client Configuration section).
2. Verify the Python path in the config points to the .venv directory.
3. Fully quit and restart your client application.
4. Check your client's logs for error messages.
5. 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).

📄 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.