Crelate MCP Server

Model Context Protocol (MCP) server for the Crelate ATS/CRM API. Enables Claude Code and other MCP clients to interact with Crelate recruiting and staffing workflows.

GitHub: https://github.com/mrchevyceleb/crelate-mcp

Quick Start

# Clone the repository
git clone https://github.com/mrchevyceleb/crelate-mcp.git
cd crelate-mcp

# Install dependencies
uv venv
uv pip install mcp httpx python-dotenv

# Configure your API key
cp .env.example .env
# Edit .env and add your CRELATE_API_KEY

# Add to Claude Code (see Configuration section below)

Features

Core CRUD Operations

Contacts: List, get, create, update contacts
Candidates: List, get, create candidates
Jobs: List, get, create job positions
Companies: List, get, create companies
Notes: Create notes and attach to records
Tasks: Create tasks and attach to records

Comprehensive Reporting & Analytics (33 tools)

Activity Reports: Track interactions, touchpoints, and engagement history
Pipeline Reports: Analyze candidate flow through job pipelines
Placement Reports: Track successful hires and metrics
Source Tracking: Identify where candidates and contacts originated
User Activity: Monitor team productivity and activity
Financial Reports: Track invoicing and payment data
Aggregate Metrics: High-level counts and organization stats
Workflow Analysis: Analyze categorization and pipeline stages

Prerequisites

Python 3.10+
uv (Python package manager)
Crelate API key

Getting Your Crelate API Key

Log into your Crelate account at https://app.crelate.com
Navigate to Settings → My Settings & Preferences
Find your API key in the API section
Copy the key for configuration

Note: Your organization administrator controls API access via Settings → Advanced Settings → User Roles.

Installation

1. Clone or navigate to the project

cd ~/mcp-projects/crelate-mcp

2. Create environment file

cp .env.example .env

Edit .env and add your Crelate API key:

CRELATE_API_KEY=your_actual_api_key_here

3. Install dependencies

uv pip install -e .

Configuration

Add to Claude Code

Edit your MCP configuration file at C:\Users\mtjoh\.claude.json:

{
  "projects": {
    "C:\\Users\\mtjoh": {
      "mcpServers": {
        "crelate": {
          "command": "uv",
          "args": ["run", "C:\\Users\\mtjoh\\mcp-projects\\crelate-mcp\\server.py"],
          "env": {
            "CRELATE_API_KEY": "your_api_key_here"
          }
        }
      }
    }
  }
}

Restart Claude Code after adding the configuration.

Available Tools

Contacts

list_contacts(limit, offset, search) - List contacts with pagination and search
get_contact(contact_id) - Get detailed contact information
create_contact(first_name, last_name, email, phone, company_name, title) - Create new contact
update_contact(contact_id, ...) - Update existing contact

Candidates

list_candidates(limit, offset, search) - List candidates with pagination and search
get_candidate(candidate_id) - Get detailed candidate information
create_candidate(first_name, last_name, email, phone, current_title, current_company) - Create new candidate

Jobs

list_jobs(limit, offset, status) - List jobs with optional status filter
get_job(job_id) - Get detailed job information
create_job(name, company_name, location, description) - Create new job posting

Companies

list_companies(limit, offset, search) - List companies with pagination and search
get_company(company_id) - Get detailed company information
create_company(name, website, industry, location) - Create new company

Notes & Tasks

create_note(body, contact_id, candidate_id, company_id, job_id) - Create note and attach to record
create_task(body, due_date, contact_id, candidate_id, company_id, job_id) - Create task and attach to record

Reporting & Analytics Tools

Activity Reports

Track interactions, touchpoints, and engagement history:

get_activities(limit, offset, activity_type) - List all activities with optional type filter
get_activity_count(activity_type) - Get total count of activities by type
get_contact_history(contact_id, limit, offset) - Get complete activity history for a contact
get_job_history(job_id, limit, offset) - Get complete activity history for a job

Pipeline & Application Reports

Analyze candidate flow through job pipelines:

get_applications(job_id, limit, offset) - List all applications for a specific job
get_application_count(job_id, status) - Count applications by job and optional status
get_job_contacts(job_id, limit, offset) - List all contacts associated with a job
get_job_contact_history(job_id, contact_id, limit, offset) - Get interaction history between job and contact

Placement Reports

Track successful hires and placement metrics:

get_placements(limit, offset, start_date, end_date) - List placements with date range filtering
get_placement_info(placement_id) - Get detailed information about a specific placement

Source Tracking

Identify where candidates and contacts originated:

get_contact_sources(limit, offset) - List all contact sources with usage stats
get_company_sources(limit, offset) - List all company sources with usage stats

User Activity & Productivity

Monitor team member activity and productivity:

get_users(limit, offset) - List all users in the organization
get_user_count() - Get total count of active users
get_user_info(user_id) - Get detailed information about a specific user
get_current_user() - Get information about the authenticated user

Financial Reports

Track invoicing and payment data:

get_invoices(limit, offset, status) - List invoices with optional status filter
get_invoice_count(status) - Count invoices by status
get_invoice_info(invoice_id) - Get detailed information about a specific invoice
get_payments(invoice_id, limit, offset) - List payments for a specific invoice

Aggregate Metrics & Organization

High-level counts and organization information:

get_contact_count(search) - Get total count of contacts with optional search filter
get_job_count(status) - Get total count of jobs with optional status filter
get_company_count(search) - Get total count of companies with optional search filter
get_organization_info() - Get information about the Crelate organization/account

Tags & Workflow Analysis

Analyze categorization and pipeline stages:

get_tags(limit, offset, entity_type) - List tags with optional entity type filter
get_tag_categories(limit, offset) - List all tag categories
get_workflow_statuses(entity_type, limit, offset) - List workflow statuses by entity type

Usage Examples

In Claude Code

Once configured, you can interact with Crelate using natural language:

"List the most recent 10 candidates"
"Get details for contact ID 12345"
"Create a new candidate named John Smith with email john@example.com"
"Add a note to candidate 67890 saying 'Great interview, moving to next round'"
"Create a task for job 54321 due tomorrow at 3pm"

Direct Python Usage

from server import list_contacts, get_contact, create_candidate

# List contacts
contacts = await list_contacts(limit=10, search="Smith")

# Get specific contact
contact = await get_contact("12345")

# Create candidate
new_candidate = await create_candidate(
    first_name="Jane",
    last_name="Doe",
    email="jane@example.com",
    current_title="Software Engineer"
)

API Reference

This MCP server wraps the Crelate API v3.

Official Documentation:

Swagger UI: https://app.crelate.com/api/pub/v1/docs/g/index
API Docs: https://app.crelate.com/api3/docs
Developer Guide: https://help.crelate.com/en/articles/4120536-crelate-api-developer-guide

Base URL: https://app.crelate.com/api3

Authentication: API key passed as query parameter

Important Notes

Date Format

All dates must be in ISO 8601 format in UTC timezone: `` 2026-01-20T15:00:00Z ``

Required Fields

Company: name
Job: name
Note: body
Task: body
Contact: firstName, lastName
Candidate: firstName, lastName

Lookups

When creating records with relationships (e.g., contact with company), Crelate supports:

Providing an existing record ID to link
Providing name fields only to auto-create new records

Troubleshooting

API Key Issues

If you get authentication errors:

Verify your API key in Crelate settings
Check that the key is correctly set in .env or MCP config
Ensure your user role has API access enabled

Connection Issues

# Test the server directly
cd ~/mcp-projects/crelate-mcp
uv run server.py

MCP Not Showing in Claude Code

Verify configuration in ~/.claude.json
Check that the server isn't in disabledMcpServers array
Restart Claude Code
Use /mcp command to check server status

Development

Project Structure

crelate-mcp/
├── server.py          # Main MCP server implementation
├── pyproject.toml     # Python dependencies
├── .env.example       # Environment template
└── README.md          # This file

Adding New Tools

To add new Crelate API endpoints:

Add a new tool function with @mcp.tool() decorator
Use make_crelate_request() helper for API calls
Follow existing patterns for parameter handling
Update this README with the new tool

Testing

# Test individual tools
import asyncio
from server import list_contacts

async def test():
    result = await list_contacts(limit=5)
    print(result)

asyncio.run(test())

Support

Crelate API Support: https://help.crelate.com/en/collections/2434134-api-documentation

MCP Documentation: https://modelcontextprotocol.io

License

MIT License - See LICENSE file for details

Project Info

Version: 0.1.0 Author: Matt Johnston Project: YourProfitPartners / Work With Your Handz Created: January 14, 2026

Crelate MCP Server