Loxo MCP Server

A Model Context Protocol (MCP) server that gives Claude direct access to the Loxo recruitment platform. Version 1.5.0 provides 28 tools covering the full recruiter workflow: searching and researching candidates, managing job pipelines, tracking activity and communication, working with companies, and maintaining candidate records. Tool descriptions guide Claude to surface recruiter intake notes and intel-rich activity history — so it can answer "where did we leave things with this candidate?" without you having to dig.

Installation

Option 0: Install via Smithery (easiest)

Install automatically for Claude Desktop via Smithery:

npx -y @smithery/cli install loxo-mcp-server --client claude

Option 1: Local Installation

# Clone the repository
git clone [repository-url]
cd loxo-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Option 2: Docker Installation

# Clone the repository
git clone [repository-url]
cd loxo-mcp-server

# Build the Docker image
docker build -t loxo-mcp-server .

# Or use Docker Compose
docker-compose build

Related MCP server: LinkedIn Model Context Protocol (MCP) Server

Configuration

Copy the provided .env.example file to .env and fill in your values:

cp .env.example .env

Then update the .env file with your configuration:

LOXO_API_KEY=your_api_key
LOXO_DOMAIN=app.loxo.co
LOXO_AGENCY_SLUG=your_agency_slug

Required environment variables:

• LOXO_API_KEY: Your Loxo API key

• LOXO_AGENCY_SLUG: Your agency's slug in Loxo

• LOXO_DOMAIN: (Optional) Defaults to 'app.loxo.co'

Docker Configuration

When using Docker, environment variables are automatically loaded from your .env file via Docker Compose, or can be passed directly:

Using Docker Compose (recommended):

# Ensure your .env file is configured
docker-compose up

Using Docker directly:

docker run -i \
  -e LOXO_API_KEY=your_api_key \
  -e LOXO_AGENCY_SLUG=your_agency_slug \
  -e LOXO_DOMAIN=app.loxo.co \
  loxo-mcp-server

Note: The -i flag is required because MCP servers communicate over stdin/stdout.

Usage

Running the Server

Locally:

npm start

With Docker Compose:

docker-compose up

With Docker directly:

docker run -i \
  -e LOXO_API_KEY=your_api_key \
  -e LOXO_AGENCY_SLUG=your_agency_slug \
  loxo-mcp-server

Integrating with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Local installation:

{
  "mcpServers": {
    "loxo": {
      "command": "node",
      "args": ["/path/to/loxo-mcp-server/build/index.js"],
      "env": {
        "LOXO_API_KEY": "your_api_key",
        "LOXO_AGENCY_SLUG": "your_agency_slug",
        "LOXO_DOMAIN": "app.loxo.co"
      }
    }
  }
}

Docker installation:

{
  "mcpServers": {
    "loxo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "LOXO_API_KEY=your_api_key",
        "-e", "LOXO_AGENCY_SLUG=your_agency_slug",
        "-e", "LOXO_DOMAIN=app.loxo.co",
        "loxo-mcp-server"
      ]
    }
  }
}

Workflow Examples

Preparing a client briefing pack

"Prepare a briefing pack for the Northvale role."

1. loxo_search_jobs — find the Northvale job and get its ID

2. loxo_get_job_pipeline — get all candidates and their current stage

3. loxo_get_candidate_brief (per candidate) — pull intake notes, contact details, and recent intel-rich activities in one call

4. Compile into a structured briefing document with current stage, motivations, compensation expectations, and recent touchpoints

Pipeline status update

"Give me a status update on all active candidates."

1. loxo_get_job_pipeline — retrieve all candidates on the role with their stage

2. loxo_get_candidate_brief (per candidate) — get intake notes and recent activity to summarise where each conversation stands

3. Deliver a concise status summary: stage, last contact, next step

Matching candidates to a new role

"Who from our database would suit this new CFO role?"

1. loxo_search_candidates — search by title, skills, sector, and tags using Lucene queries

2. loxo_get_candidate_brief (for shortlisted candidates) — review intake notes and activity history to assess genuine fit and current availability

3. Surface the best matches with supporting evidence from recruiter notes and recent conversations

Available Tools

Find & Research Candidates

• loxo_search_candidates — Search the candidate database using Lucene queries. Filter by current title, past employers, skills, tags, location, or any combination. Returns 100 results per page including skillsets and tags, so you can filter without extra calls. Follow up with loxo_get_candidate_brief for shortlisted candidates.

• loxo_get_candidate — Full candidate profile including bio, current role, skills, tags, compensation, and the recruiter's intake and call notes (in the description field). The description field is often the richest source of candidate intelligence: motivations, personal circumstances, compensation expectations, and role preferences.

• loxo_get_candidate_brief — The go-to tool when you need full candidate context. Returns profile (including intake notes), all contact details, and recent intel-rich activities (calls, emails, notes, interviews — with pipeline noise filtered out) in a single call. Use this before drafting outreach, preparing briefing packs, or evaluating candidate-role fit. Supports pagination via scroll_id to dig back into older activity.

• loxo_get_person_emails — All email addresses on file for a candidate, with type labels (work, personal, etc.).

• loxo_get_person_phones — All phone numbers on file for a candidate, with type labels (mobile, work, home, etc.).

• loxo_list_person_job_profiles — Complete work history list for a candidate: all roles, companies, and dates.

• loxo_get_person_job_profile_detail — Detailed information about a specific role in a candidate's work history. Use after loxo_list_person_job_profiles when you need the full description for a particular position.

• loxo_list_person_education_profiles — Complete education history for a candidate: all degrees, schools, and dates.

• loxo_get_person_education_profile_detail — Detailed information about a specific education entry. Use after loxo_list_person_education_profiles when you need the full details for a particular qualification.

Manage Pipeline & Jobs

• loxo_search_jobs — Search open roles using Lucene queries (title, location, or any combination). Uses page-based pagination.

• loxo_get_job — Full job details including description, requirements, compensation, status, and hiring team.

• loxo_get_job_pipeline — All candidates currently on a job with their pipeline stage (sourced, screened, interviewing, offer, placed). Returns candidate IDs and stages; follow up with loxo_get_candidate_brief for full context on each person.

• loxo_add_to_pipeline — Add a candidate to a job's pipeline. Places them at the first stage and makes them visible in loxo_get_job_pipeline.

Track Activity & Communication

• loxo_get_candidate_activities — Full unfiltered activity timeline for a candidate: all calls, emails, meetings, notes, pipeline moves, and automation events, most recent first. Use when you need the complete raw history. For a cleaner, intel-focused view, use loxo_get_candidate_brief instead.

• loxo_log_activity — Record a completed activity (call, email, meeting, interview) against a candidate. Use loxo_get_activity_types first to find the correct activity type ID.

• loxo_schedule_activity — Create a future activity (call, meeting, interview) for a candidate. Use loxo_get_activity_types first to find the correct activity type ID.

• loxo_get_todays_tasks — All scheduled items for today (or a date range you specify). Optionally filter by user.

• loxo_get_activity_types — List all activity types and their IDs. Call this before logging or scheduling activities to get the correct activity_type_id.

Companies & Reference Data

• loxo_search_companies — Search the company database using Lucene queries. Uses cursor-based pagination with scroll_id.

• loxo_get_company_details — Full company profile including description, contacts, relationships, and status.

• loxo_list_users — All users in your Loxo agency (recruiters, coordinators, etc.) with names and emails. Use to find user_id values for filtering tasks or checking record ownership.

• loxo_list_skillsets — All Skillset and Sector Experience options with their IDs. Use to find valid skillset_ids and sector_ids values before calling loxo_update_candidate.

• loxo_list_source_types — All candidate source types (LinkedIn, API, Referral, etc.) with their IDs. Use to find valid source_type_id values.

• loxo_list_person_types — All person type categories (Active Candidate, Prospect Candidate, etc.) with their IDs. Use to find valid person_type_id values.

Candidate Management

• loxo_create_candidate — Create a new candidate record with name, contact info, and current role. After creating, use loxo_update_candidate to set tags, skillsets, person type, and source type.

• loxo_update_candidate — Update an existing candidate's details: profile fields, tags, skillsets, sector, person type, and source type. Use loxo_list_skillsets and loxo_list_person_types to look up valid IDs first.

• loxo_upload_resume — Upload a CV or resume file to a candidate's profile. Accepts base64-encoded file content. The file appears in the Resumes section of their Loxo record.

Architecture

Built on the Model Context Protocol SDK, communicating over stdio for seamless integration with Claude Desktop and Claude.ai.

• v1.5.0 — 28 tools; tool descriptions guide Claude to surface recruiter intake notes (description field) and intel-rich activities (calls, emails, notes, interviews) while filtering out pipeline automation noise

• All API calls go to https://{LOXO_DOMAIN}/api/{LOXO_AGENCY_SLUG}/... with Bearer token auth

• POST/PATCH request bodies use application/x-www-form-urlencoded with bracket notation (e.g. person[name])

• All endpoints verified against the official Loxo OpenAPI specification

Pagination

Two pagination styles are used depending on the endpoint:

• Cursor-based (scroll_id) — used by candidates, companies, schedule items, and activities. Pass the scroll_id from one response to the next to walk through pages.

• Page-based (page / per_page) — used by jobs. Pass page=1, page=2, etc.

Activity & Event System

All activity tracking (calls, emails, meetings, notes, pipeline moves) goes through the person_events API:

• Scheduled activities — use loxo_schedule_activity with a future created_at datetime

• Completed activities — use loxo_log_activity; the current timestamp is applied automatically

• Activities can be linked to a person, a job, and/or a company

• loxo_get_candidate_brief filters activities to intel-rich types only (excludes pipeline automation events and other low-signal entries)

Development

Local Development

# Run in development mode with watch mode
npm run dev

# Build the project
npm run build

# Start the server
npm start

Docker Development

# Rebuild after code changes
docker-compose build

# Run with live logs
docker-compose up

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down