# osherai/bullhorn-mcp-python architecture

> Architecture diagram of the GitHub repository osherai/bullhorn-mcp-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/osherai/bullhorn-mcp-python
- Repository: https://github.com/osherai/bullhorn-mcp-python

## Overview

Bullhorn MCP exposes read-only CRM lookup tools to MCP-compatible assistants. The workflow runs from a client tool request through a registered server tool, which obtains a configured API client and returns formatted results. Tool stages cover job and candidate lists, individual records, Lucene searches, and SQL-like queries. Internally, configuration feeds OAuth/session management, while the REST client uses that session to call Bullhorn. Source excerpts support the core calls; broader entity coverage is documented in the README.

Main entry points: [`src/bullhorn_mcp/server.py`](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py) (MCP server), [`src/bullhorn_mcp/client.py`](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/client.py) (REST client), [`src/bullhorn_mcp/auth.py`](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/auth.py) (OAuth sessions), [`src/bullhorn_mcp/config.py`](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/config.py) (Environment config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_server["MCP server<br/>[server.py]"]
  node_job_tools["Job tools<br/>[server.py]"]
  node_candidate_tools["Candidate tools<br/>[server.py]"]
  node_record_tools["Record lookup<br/>[server.py]"]
  node_lucene_tool["Lucene search<br/>[server.py]"]
  node_where_tool["WHERE query<br/>[server.py]"]
end

subgraph group_setup["Configuration and auth"]
  node_config["Environment config<br/>[config.py]"]
  node_auth["OAuth sessions<br/>[auth.py]"]
end

subgraph group_crm["CRM access"]
  node_client["REST client<br/>[client.py]"]
end

node_assistant(("MCP-compatible assistant"))
node_oauth_service{{"Bullhorn OAuth"}}
node_crm_api{{"Bullhorn REST API"}}

node_assistant -->|"sends tool requests"| node_server
node_server -->|"registers tools"| node_job_tools
node_server -->|"registers tools"| node_candidate_tools
node_server -->|"registers tools"| node_record_tools
node_server -->|"registers tool"| node_lucene_tool
node_server -->|"registers tool"| node_where_tool
node_server -->|"loads settings"| node_config
node_server -->|"creates auth"| node_auth
node_server -->|"creates client"| node_client
node_job_tools -->|"searches jobs"| node_client
node_candidate_tools -->|"searches candidates"| node_client
node_record_tools -->|"gets records"| node_client
node_lucene_tool -->|"searches entities"| node_client
node_where_tool -->|"queries entities"| node_client
node_client -->|"reads session"| node_auth
node_auth -->|"uses credentials"| node_config
node_auth -->|"authenticates and refreshes"| node_oauth_service
node_client -->|"requests CRM data"| node_crm_api

click node_server "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py"
click node_job_tools "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py"
click node_candidate_tools "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py"
click node_record_tools "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py"
click node_lucene_tool "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py"
click node_where_tool "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py"
click node_config "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/config.py"
click node_auth "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/auth.py"
click node_client "https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_job_tools,node_candidate_tools,node_record_tools,node_lucene_tool,node_where_tool toneBlue
class node_config,node_auth toneAmber
class node_client,node_crm_api toneMint
class node_assistant,node_oauth_service toneIndigo
```

## Components

### MCP interface

- [MCP server](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py): `src/bullhorn_mcp/server.py`
- [Job tools](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py): `src/bullhorn_mcp/server.py`
- [Candidate tools](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py): `src/bullhorn_mcp/server.py`
- [Record lookup](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py): `src/bullhorn_mcp/server.py`
- [Lucene search](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py): `src/bullhorn_mcp/server.py`
- [WHERE query](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/server.py): `src/bullhorn_mcp/server.py`

### Configuration and auth

- [Environment config](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/config.py): `src/bullhorn_mcp/config.py`
- [OAuth sessions](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/auth.py): `src/bullhorn_mcp/auth.py`

### CRM access

- [REST client](https://github.com/osherai/bullhorn-mcp-python/blob/main/src/bullhorn_mcp/client.py): `src/bullhorn_mcp/client.py`

### Other components

- **MCP-compatible assistant**
- **Bullhorn OAuth**
- **Bullhorn REST API**

## Connections

- MCP-compatible assistant → MCP server: sends tool requests (evidence: `README.md`)
- MCP server → Job tools: registers tools (evidence: `src/bullhorn_mcp/server.py`)
- MCP server → Candidate tools: registers tools (evidence: `src/bullhorn_mcp/server.py`)
- MCP server → Record lookup: registers tools (evidence: `src/bullhorn_mcp/server.py`)
- MCP server → Lucene search: registers tool (evidence: `src/bullhorn_mcp/server.py`)
- MCP server → WHERE query: registers tool (evidence: `src/bullhorn_mcp/server.py`)
- MCP server → Environment config: loads settings (evidence: `src/bullhorn_mcp/server.py`)
- MCP server → OAuth sessions: creates auth (evidence: `src/bullhorn_mcp/server.py`)
- MCP server → REST client: creates client (evidence: `src/bullhorn_mcp/server.py`)
- Job tools → REST client: searches jobs (evidence: `src/bullhorn_mcp/server.py`)
- Candidate tools → REST client: searches candidates (evidence: `src/bullhorn_mcp/server.py`)
- Record lookup → REST client: gets records (evidence: `src/bullhorn_mcp/server.py`)
- Lucene search → REST client: searches entities (evidence: `src/bullhorn_mcp/server.py`)
- WHERE query → REST client: queries entities (evidence: `src/bullhorn_mcp/server.py`)
- REST client → OAuth sessions: reads session (evidence: `src/bullhorn_mcp/client.py`)
- OAuth sessions → Environment config: uses credentials (evidence: `src/bullhorn_mcp/auth.py`)
- OAuth sessions → Bullhorn OAuth: authenticates and refreshes (evidence: `src/bullhorn_mcp/auth.py`)
- REST client → Bullhorn REST API: requests CRM data (evidence: `src/bullhorn_mcp/client.py`)
