Bullhorn MCP Server Released

Ask your CRM questions in plain English. Get actual answers.

If you’ve spent fifteen minutes clicking through Bullhorn screens to answer “Who are our Python candidates added recently?”, you know exactly why we built this.

Bullhorn is the industry standard for recruitment CRM. There’s a reason for that. But all that power means complexity. Finding information means navigating views, writing Boolean searches, and cross-referencing screens. For consultants who should be building relationships instead of fighting software, the friction adds up fast.

So we built an open-source tool that lets AI assistants query Bullhorn directly. Plain English in, useful data out. No Boolean syntax to memorise. No clicking through five screens for one answer.

This post explains what it is, why we made it free, and how to set it up yourself.

The Real Cost of Slow Data Access

Every recruitment agency has years of candidate relationships, placement history, and client preferences locked in their CRM. The problem isn’t the data but getting to it.

Here’s a typical scenario: a client calls with an urgent requirement. Senior software engineer in Sydney, available now, financial services experience. The consultant knows they have candidates who fit. But finding them means:

1. Opening candidate search
2. Remembering Boolean syntax for skills
3. Filtering by location
4. Cross-referencing availability
5. Checking placement history
6. Reading old notes

Ten minutes later, there’s a shortlist. Ten minutes that could’ve been spent calling candidates.

Multiply this across every search, every day, every consultant. The agency that responds in ten minutes wins the placement. The one that responds in an hour watches the candidate accept another offer.

What’s MCP?

Model Context Protocol is an open standard from Anthropic that lets AI assistants connect to external data sources. Think of it as a translator between AI models and where your data actually lives.

Without MCP, AI assistants only know their training data or what you paste in. With MCP, they can query live databases, call APIs, and interact with external services while you control the security boundaries.

The point: AI gets useful when it can access real, current data rather than just generating generic responses. An AI that can check your actual CRM beats one that can only talk about CRM best practices.

MCP works with Claude Desktop, Cursor, Windsurf, VS Code extensions, and others. One MCP server works across multiple AI tools.

The Bullhorn MCP Server

We’ve released an open-source MCP server connecting AI assistants to Bullhorn’s REST API. It’s Python, requires no paid middleware or per-seat licensing, and you can have it running in under fifteen minutes.

Six tools cover most day-to-day queries:

List Jobs – Search job orders with natural language.

• “Show me all open jobs added this month”
• “Find engineering roles above $150k”
• “What jobs are we working on for Acme Corp?”

List Candidates – Search your candidate database.

• “Find candidates with React experience in Melbourne”
• “Who are our most recently added project managers?”
• “Show me available contractors with AWS certs”

Get Job Details – Full information for a specific job.

• “Tell me everything about job #7024”
• “What are the requirements for the Senior Developer at TechCorp?”

Get Candidate Details – Complete candidate profiles.

• “Show me the full profile for candidate #12345”
• “What’s the work history for Jane Smith?”

Search Entities – Query any Bullhorn entity type: placements, corporations, contacts, submissions, appointments.

• “Show me all placements made last quarter”
• “Which clients have we placed the most candidates with?”
• “Find all submissions for job #7024”

Query Entities – SQL-like queries for complex filtering.

• “Find all jobs where salary is greater than $120,000”
• “Show candidates added in the last 30 days with status Active”
• “List placements where the fee was above $20,000”

What This Actually Looks Like

The urgent client call

Before: Client calls at 4:45 PM needing a .NET developer shortlist by end of day. Consultant spends 20 minutes on searches. Sends shortlist at 5:15 PM.

After: Consultant asks “Find our top 10 .NET developers in Sydney who are currently available, sorted by most recent contact.” Results in seconds. Shortlist sent at 4:48 PM.

The Monday pipeline review

Before: Manager spends an hour pulling numbers from Bullhorn reports. Exports to spreadsheet. Builds slides. Still goes back to Bullhorn for ad-hoc questions during the meeting.

After: Manager asks questions live:

• “How many placements did we make last week?”
• “What’s our open job count by client?”
• “Who has the most submissions this month?”
• “Show me jobs open more than 30 days”

Real-time answers. Drill into any number on the spot.

The candidate catch-up

Before: Consultant wants to reconnect with neglected candidates. Manually searches by owner, sorts by last contact, cross-references calendar. 30 minutes to build a call list.

After: “Show me my candidates with no activity in 60 days, sorted by last placement date.” Done.

The BD meeting

Before: Sales director needs to know which clients have dropped their job volume versus last year. Requests report from ops. Waits two days. Gets a spreadsheet that raises more questions.

After: “Compare placement count by client this quarter versus same quarter last year. Show clients where volume dropped more than 20%.” Immediate. Follows up with “Show me contact history for [client]” to understand what changed.

The compliance check

Before: Compliance officer verifies all healthcare placements have required certifications documented. Manual review of each record. Most of a day.

After: “List all healthcare sector placements from the last 12 months with candidate name, role, and certification status.” Minutes. Then “Show full profile for candidates missing certifications.”

How It Works

For those who want the technical details.

Authentication

The server implements Bullhorn’s OAuth 2.0 flow:

1. Exchanges your API credentials for an authorisation code
2. Converts the auth code to access and refresh tokens
3. Gets a BhRestToken and your instance’s REST URL
4. Handles token expiration automatically

Credentials live in a local .env file. They never leave your machine. The server talks directly to Bullhorn’s API. No intermediary, no cloud processing, no third-party access.

Read-only by design

The server only reads. No create, update, or delete. This is deliberate. AI can query your data, but changes should go through normal Bullhorn workflows with their audit trails and approvals.

Regional servers

Bullhorn has data centres in US, EMEA, and APAC. The server handles regional redirects during auth, connecting to the right instance regardless of where your data lives.

Query methods

The server uses both Bullhorn query interfaces:

• Search API with Lucene syntax for full-text search
• Query API with SQL-like WHERE clauses for exact filtering

The AI picks the right one based on your question, or you can specify.

Getting Started

Prerequisites

• Python 3.10+
• Bullhorn CRM account with API access
• API credentials (Client ID, Client Secret, Username, Password)

No API credentials? Contact your Bullhorn admin or account manager. They can set up OAuth app credentials and a service account.

Installation

1. Clone the repo:

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

2. Set up environment:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

3. Configure credentials:

cp .env.example .env
# Edit .env with your Bullhorn API credentials

4. Test the connection:

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'Connected successfully! Found {len(jobs)} jobs.')
"

Connect to your AI

Works with any MCP-compatible client. For 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"
    }
  }
}

Restart Claude Desktop. Start asking questions.

The README has configs for Cursor, Windsurf, VS Code with Cline, VS Code with Continue, and Zed.

Why Free?

We could have charged for this. Per-seat licensing, monthly subscriptions, enterprise tiers. The usual.

We didn’t, for a few reasons.

Barrier to entry. Recruitment agencies already pay for Bullhorn, ATS integrations, job boards, and a dozen other subscriptions. Adding another fee for basic data access felt wrong. It’s your data. You shouldn’t pay again to query it.

Trust. When connecting AI to your CRM with candidate and client data, you should see exactly what that connection does. Open source means you can read every line, verify it only reads, confirm your credentials stay local.

Community benefit. Recruitment has shared problems. Open source means fixes and features help everyone, not just paying customers.

Our actual business. We’re an AI consultancy, not a software licensing company. Our value is helping businesses implement AI solutions for their specific needs. Open-sourcing the generic bits lets us focus on custom work where we actually add something.

What It Isn’t

Being honest about limitations:

What it is:

• Read-only query interface to Bullhorn (intentionally at this point)
• Faster answers to routine CRM questions
• Free alternative to paid connectors
• A foundation you can extend

What it isn’t:

• A replacement for Bullhorn’s interface for data entry
• A reporting platform (though it can feed one)
• A way to write data (create candidates, update jobs)
• A managed service. You run it, you maintain it.

Security notes:

• Credentials stored locally in plaintext (standard for dev tools)
• Anyone with machine access could read your .env
• Consider file permissions and access controls
• Direct API calls follow your normal network policies

API limits:

• Bullhorn has rate limits
• Large result sets need pagination
• Complex queries may timeout
• Historical access depends on your retention settings

What’s Coming

This release covers core query functionality. We’re considering:

• Saved queries for instant recall
• Chained queries for complex questions
• CSV and formatted table exports
• More entity type support
• Pre-built query templates for common metrics

Feature requests and contributions welcome on GitHub.

Wrapping Up

The gap between having data and using it is one of the most annoying problems in business software. CRMs capture everything but surfacing the right info at the right moment takes expertise most people don’t have time to develop.

AI can bridge that gap, but only with access to real data. MCP makes that work in a secure, standardized way. Open source means the benefits aren’t gated by budget.

If you use Bullhorn and you’re tired of the friction, try it. Fifteen minutes to set up, costs nothing. Worst case, you’ve lost fifteen minutes. Best case, you stop dreading data questions.

Repository: github.com/osherai/bullhorn-mcp-python

About Osher Digital

Osher Digital helps businesses put AI to practical use. Automation workflows, custom integrations, solutions that actually work without enterprise complexity.

Want to talk about custom AI for your business? Get in touch