Skip to main content
Glama
Crelate MCP Server

Crelate MCP Server

by mrchevyceleb

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)

Related MCP server: codebeamer-mcp

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

  1. Log into your Crelate account at https://app.crelate.com

  2. Navigate to Settings → My Settings & Preferences

  3. Find your API key in the API section

  4. 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:

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:

  1. Verify your API key in Crelate settings

  2. Check that the key is correctly set in .env or MCP config

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

  1. Verify configuration in ~/.claude.json

  2. Check that the server isn't in disabledMcpServers array

  3. Restart Claude Code

  4. 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:

  1. Add a new tool function with @mcp.tool() decorator

  2. Use make_crelate_request() helper for API calls

  3. Follow existing patterns for parameter handling

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

Available Tools

42 tools
create_candidateA

Create a new candidate in Crelate.

Args: first_name: Candidate's first name (required) last_name: Candidate's last name (required) email: Candidate's email address phone: Candidate's phone number current_title: Candidate's current job title current_company: Candidate's current company

Returns: JSON string containing the created candidate details including ID

Inputs: last_name (required), first_name (required), email, phone, +2 more. Returns: result

create_companyB

Create a new company in Crelate.

Args: name: Company name (required) website: Company website URL industry: Company industry location: Company location

Returns: JSON string containing the created company details including ID

Inputs: name (required), website, industry, location. Returns: result

create_contactA

Create a new contact in Crelate.

Args: first_name: Contact's first name (required) last_name: Contact's last name (required) email: Contact's email address phone: Contact's phone number company_name: Associated company name title: Contact's job title

Returns: JSON string containing the created contact details including ID

Inputs: last_name (required), first_name (required), email, phone, +2 more. Returns: result

create_jobA

Create a new job/position in Crelate.

Args: name: Job title/name (required) company_name: Hiring company name location: Job location description: Job description

Returns: JSON string containing the created job details including ID

Inputs: name (required), location, description, company_name. Returns: result

create_noteA

Create a note in Crelate and optionally attach it to a record.

Args: body: Note content (required) contact_id: Optional contact ID to attach note to candidate_id: Optional candidate ID to attach note to company_id: Optional company ID to attach note to job_id: Optional job ID to attach note to

Returns: JSON string containing the created note details

Inputs: body (required), job_id, company_id, contact_id, +1 more. Returns: result

create_taskA

Create a task in Crelate and optionally attach it to a record.

Args: body: Task description (required) due_date: Optional due date in ISO 8601 format (e.g., '2026-01-20T15:00:00Z') contact_id: Optional contact ID to attach task to candidate_id: Optional candidate ID to attach task to company_id: Optional company ID to attach task to job_id: Optional job ID to attach task to

Returns: JSON string containing the created task details

Inputs: body (required), job_id, due_date, company_id, +2 more. Returns: result

get_activitiesA

Get activity/interaction history with optional filtering.

Args: limit: Maximum number of activities to return (default: 50) offset: Number of activities to skip for pagination (default: 0) contact_id: Filter by contact ID candidate_id: Filter by candidate ID job_id: Filter by job ID company_id: Filter by company ID

Returns: JSON string containing activity history (calls, emails, notes, etc.)

Inputs: limit, job_id, offset, company_id, +2 more. Returns: result

get_activity_countA

Get total count of activities with optional filtering.

Args: contact_id: Filter by contact ID candidate_id: Filter by candidate ID job_id: Filter by job ID

Returns: JSON string containing activity count

Inputs: job_id, contact_id, candidate_id. Returns: result

get_application_countA

Get count of applications with optional filtering.

Args: job_id: Filter by specific job ID status: Filter by application status

Returns: JSON string containing application count

Inputs: job_id, status. Returns: result

get_applicationsC

Get job applications with filtering options.

Args: limit: Maximum number of applications to return (default: 50) offset: Number of applications to skip for pagination (default: 0) job_id: Filter by specific job ID candidate_id: Filter by specific candidate ID status: Filter by application status

Returns: JSON string containing applications (candidate pipeline data)

Inputs: limit, job_id, offset, status, +1 more. Returns: result

get_candidateA

Get detailed information about a specific candidate.

Args: candidate_id: The unique ID of the candidate

Returns: JSON string containing full candidate details including skills, experience, etc.

Inputs: candidate_id (required). Returns: result

get_companyB

Get detailed information about a specific company.

Args: company_id: The unique ID of the company

Returns: JSON string containing full company details

Inputs: company_id (required). Returns: result

get_company_countA

Get total count of companies with optional search filter.

Args: search: Optional search query to filter companies

Returns: JSON string containing company count

Inputs: search. Returns: result

get_company_sourcesA

Get all company sources for tracking where companies came from.

Args: limit: Maximum number of sources to return (default: 50) offset: Number of sources to skip for pagination (default: 0)

Returns: JSON string containing company source data

Inputs: limit, offset. Returns: result

get_contactA

Get detailed information about a specific contact.

Args: contact_id: The unique ID of the contact

Returns: JSON string containing full contact details

Inputs: contact_id (required). Returns: result

get_contact_countB

Get total count of contacts with optional search filter.

Args: search: Optional search query to filter contacts

Returns: JSON string containing contact count

Inputs: search. Returns: result

get_contact_historyA

Get interaction history for contacts.

Args: contact_id: Specific contact ID (optional) limit: Maximum number of history items to return (default: 50) offset: Number of items to skip for pagination (default: 0)

Returns: JSON string containing contact interaction history

Inputs: limit, offset, contact_id. Returns: result

get_contact_sourcesA

Get all contact sources for tracking where contacts came from.

Args: limit: Maximum number of sources to return (default: 50) offset: Number of sources to skip for pagination (default: 0)

Returns: JSON string containing contact source data

Inputs: limit, offset. Returns: result

get_current_userA

Get information about the current authenticated user.

Returns: JSON string containing current user details

Inputs: no named parameters. Returns: result

get_invoice_countB

Get count of invoices with optional status filter.

Args: status: Filter by invoice status

Returns: JSON string containing invoice count

Inputs: status. Returns: result

get_invoice_infoC

Get detailed information about a specific invoice.

Args: invoice_id: The invoice ID

Returns: JSON string containing detailed invoice information

Inputs: invoice_id (required). Returns: result

get_invoicesA

Get invoice records for financial reporting.

Args: limit: Maximum number of invoices to return (default: 50) offset: Number of invoices to skip for pagination (default: 0) status: Filter by invoice status

Returns: JSON string containing invoice data

Inputs: limit, offset, status. Returns: result

get_jobA

Get detailed information about a specific job/position.

Args: job_id: The unique ID of the job

Returns: JSON string containing full job details including description, requirements

Inputs: job_id (required). Returns: result

get_job_contact_historyA

Get interaction history for contacts on a specific job.

Args: job_id: The job ID (required) limit: Maximum number of history items to return (default: 50) offset: Number of items to skip for pagination (default: 0)

Returns: JSON string containing job-contact interaction history

Inputs: job_id (required), limit, offset. Returns: result

get_job_contactsA

Get all contacts/candidates associated with a job.

Args: job_id: The job ID (required) limit: Maximum number of contacts to return (default: 50) offset: Number of contacts to skip for pagination (default: 0)

Returns: JSON string containing contacts linked to the job

Inputs: job_id (required), limit, offset. Returns: result

get_job_countA

Get total count of jobs with optional status filter.

Args: status: Filter by job status (e.g., 'open', 'closed')

Returns: JSON string containing job count

Inputs: status. Returns: result

get_job_historyC

Get history for jobs/positions.

Args: job_id: Specific job ID (optional) limit: Maximum number of history items to return (default: 50) offset: Number of items to skip for pagination (default: 0)

Returns: JSON string containing job history

Inputs: limit, job_id, offset. Returns: result

get_organization_infoA

Get information about the current organization.

Returns: JSON string containing organization details and settings

Inputs: no named parameters. Returns: result

get_paymentsB

Get payment records for financial tracking.

Args: limit: Maximum number of payments to return (default: 50) offset: Number of payments to skip for pagination (default: 0)

Returns: JSON string containing payment data

Inputs: limit, offset. Returns: result

get_placement_infoC

Get detailed information about a specific placement.

Args: placement_id: The placement ID

Returns: JSON string containing detailed placement information

Inputs: placement_id (required). Returns: result

get_placementsA

Get placement records (successful hires).

Args: limit: Maximum number of placements to return (default: 50) offset: Number of placements to skip for pagination (default: 0) status: Filter by placement status

Returns: JSON string containing placement data including hire dates, salaries, etc.

Inputs: limit, offset, status. Returns: result

get_tag_categoriesA

Get tag categories for organizational reporting.

Args: limit: Maximum number of categories to return (default: 50) offset: Number of categories to skip for pagination (default: 0)

Returns: JSON string containing tag category data

Inputs: limit, offset. Returns: result

get_tagsB

Get tags for categorization and reporting.

Args: limit: Maximum number of tags to return (default: 50) offset: Number of tags to skip for pagination (default: 0) category: Filter by tag category

Returns: JSON string containing tag data

Inputs: limit, offset, category. Returns: result

get_user_countA

Get total count of users in the organization.

Returns: JSON string containing user count

Inputs: no named parameters. Returns: result

get_user_infoC

Get detailed information about a specific user.

Args: user_id: The user ID

Returns: JSON string containing user details and activity information

Inputs: user_id (required). Returns: result

get_usersC

Get all users in the organization.

Args: limit: Maximum number of users to return (default: 50) offset: Number of users to skip for pagination (default: 0)

Returns: JSON string containing user data for team activity analysis

Inputs: limit, offset. Returns: result

get_workflow_statusesA

Get workflow statuses for pipeline stage analysis.

Args: limit: Maximum number of statuses to return (default: 50) offset: Number of statuses to skip for pagination (default: 0)

Returns: JSON string containing workflow status data

Inputs: limit, offset. Returns: result

list_candidatesA

List candidates from Crelate.

Args: limit: Maximum number of candidates to return (default: 50) offset: Number of candidates to skip for pagination (default: 0) search: Optional search query to filter candidates

Returns: JSON string containing list of candidates

Inputs: limit, offset, search. Returns: result

list_companiesB

List companies from Crelate.

Args: limit: Maximum number of companies to return (default: 50) offset: Number of companies to skip for pagination (default: 0) search: Optional search query to filter companies

Returns: JSON string containing list of companies

Inputs: limit, offset, search. Returns: result

list_contactsA

List contacts from Crelate.

Args: limit: Maximum number of contacts to return (default: 50) offset: Number of contacts to skip for pagination (default: 0) search: Optional search query to filter contacts

Returns: JSON string containing list of contacts with id, name, email, phone

Inputs: limit, offset, search. Returns: result

list_jobsA

List jobs/positions from Crelate.

Args: limit: Maximum number of jobs to return (default: 50) offset: Number of jobs to skip for pagination (default: 0) status: Optional filter by job status (e.g., 'open', 'closed')

Returns: JSON string containing list of jobs with id, name, status, location

Inputs: limit, offset, status. Returns: result

update_contactA

Update an existing contact in Crelate.

Args: contact_id: The unique ID of the contact to update first_name: Contact's first name last_name: Contact's last name email: Contact's email address phone: Contact's phone number title: Contact's job title

Returns: JSON string containing the updated contact details

Inputs: contact_id (required), email, phone, title, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 42 tools

    Disambiguation4/5

    Most tools have distinct purposes, e.g., get_candidate vs list_candidates. However, there is potential confusion between history tools like get_contact_history, get_job_history, and get_job_contact_history, which could overlap with get_activities. Overall, the set is largely disambiguated.

    Naming Consistency3/5

    The naming follows a consistent verb_noun pattern with get_, list_, create_, and update_. However, update_contact is the only update tool, missing updates for candidates, companies, and jobs. There are no delete tools, breaking the expected CRUD pattern. The mix of get_ and list_ is acceptable but the absence of other operations is inconsistent.

    Tool Count4/5

    With 42 tools covering candidates, companies, contacts, jobs, notes, tasks, activities, applications, placements, invoices, payments, users, tags, and workflow statuses, the count is high but justifiable for the breadth of the domain. Some tools like counts and sources could be merged, but overall it's reasonable.

    Completeness2/5

    The server is heavily read-focused with many get/list/count tools but lacks update operations for most entities (only update_contact) and has no delete tools at all. Missing operations like submitting applications, moving pipeline stages, or managing placements beyond reading leave significant gaps for a recruitment CRM lifecycle.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An implementation of Claude Code as a Model Context Protocol server that enables using Claude's software engineering capabilities (code generation, editing, reviewing, and file operations) through the standardized MCP interface.
      8
      188
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive Model Context Protocol (MCP) server that integrates with the Cronlytic API to provide seamless cron job management through LLM applications like Claude Desktop.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A production-ready MCP server that exposes the Salesmate CRM to Claude Desktop, enabling search, update, and creation of contacts, deals, tasks, notes, and activities.
      8
      1
      MIT