Content
# Loxo MCP Server
A Model Context Protocol (MCP) server that provides tools for interacting with the Loxo recruitment platform API (v1.3.1). This server enables AI assistants to perform various recruitment-related tasks such as managing candidates, jobs, companies, and activities.
## Installation
### Option 1: Local Installation
```bash
# 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
```bash
# 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
```
## Configuration
Copy the provided `.env.example` file to `.env` and fill in your values:
```bash
cp .env.example .env
```
Then update the `.env` file with your configuration:
```env
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):
```bash
# Ensure your .env file is configured
docker-compose up
```
**Using Docker directly**:
```bash
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**:
```bash
npm start
```
**With Docker Compose**:
```bash
docker-compose up
```
**With Docker directly**:
```bash
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**:
```json
{
"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**:
```json
{
"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"
]
}
}
}
```
## Usage Examples
Once configured, you can interact with the Loxo MCP server through natural language conversations with Claude. Here are some example interactions:
### Finding Candidates
**You:** "Find me candidates who have worked at Google and know TypeScript"
**Claude will:**
1. Use `search-candidates` with query: `job_profiles.company_name:"Google" AND skills:"TypeScript"`
2. Return a list of matching candidates with their current roles, locations, **skills, and tags visible in search results** (no need to fetch full profiles for basic filtering)
---
**You:** "Give me all candidates in deal advisory, transaction services, or transaction advisory with financial due diligence skills at director level"
**Claude will:**
1. Use `search-candidates` with complex query: `(current_title:("Deal Advisory" OR "Transaction Services" OR "Transaction Advisory")) AND current_title:"Director" AND skills:"financial due diligence"`
2. Return comprehensive results (100 per page by default) with skills visible
3. Filter and present matching candidates in a single response
---
**You:** "Show me more details about candidate ID 12345"
**Claude will:**
1. Use `get-candidate` to retrieve full profile
2. Display comprehensive information including job history, education, contact details, and skills
---
**You:** "Get the complete work history for candidate 12345"
**Claude will:**
1. Use `list-person-job-profiles` to get all job entries
2. Optionally use `get-person-job-profile-detail` for each entry to show full details
---
### Advanced Search Techniques
The `search-candidates` tool supports complex Lucene queries for precise candidate filtering.
**IMPORTANT - Field Name Mapping:**
- Queries use `skills` (search index): `query='skills:"Python"'`
- Responses return `skillsets` (API field): `{skillsets: "Python, JavaScript"}`
**Multiple Role Types with Skills:**
```
query='(current_title:("Deal Advisory" OR "Transaction Services" OR "Transaction Advisory"))
AND current_title:"Director"
AND skills:"financial due diligence"'
```
**Past Companies with Multiple Skills:**
```
query='(job_profiles.company_name:("KPMG" OR "Deloitte" OR "PwC" OR "EY"))
AND skills:("M&A" OR "financial due diligence")'
```
**Combined Current and Past Experience:**
```
query='current_title:"Director"
AND job_profiles.company_name:("Big 4")
AND skills:"financial modeling"'
```
**Using Tags:**
```
query='all_raw_tags:"key account" AND current_title:"VP"'
```
**Data Quality - Finding Missing Fields:**
```
# Candidates without skills
query='NOT _exists_:skills'
# Candidates without tags
query='NOT _exists_:all_raw_tags'
# Candidates missing location
query='NOT _exists_:location'
```
**Benefits:**
- Returns **100 results per page** (vs 20 previously) for fewer API calls
- **Skillsets and tags visible in search results** - no need to fetch full profiles for filtering
- Construct comprehensive queries upfront to get all relevant candidates in 1-2 API calls instead of 10+
- Use `NOT _exists_:` to find incomplete profiles for data cleanup
---
### Managing Activities
**You:** "What are my tasks for today?"
**Claude will:**
1. Use `get-todays-tasks` with today's date range
2. Show all scheduled activities and tasks
---
**You:** "Schedule a follow-up call with candidate 12345 for next Tuesday at 2pm"
**Claude will:**
1. Use `get-activity-types` to find the call activity type ID
2. Use `schedule-activity` with the candidate ID, activity type, and the specified date/time
3. Confirm the activity was scheduled
---
**You:** "Log that I just had a phone screen with candidate 12345. They were great, very strong React skills."
**Claude will:**
1. Use `get-activity-types` to find phone screen activity type ID
2. Use `log-activity` with the candidate ID, activity type, and your notes
3. Confirm the activity was logged
---
### Searching Jobs
**You:** "Find all remote Senior Engineer positions"
**Claude will:**
1. Use `search-jobs` with query containing title and location filters
2. Display matching jobs with key details
---
**You:** "Show me details for job 54321"
**Claude will:**
1. Use `get-job` to retrieve full job posting
2. Display complete job information including description, requirements, and status
---
### Working with Companies
**You:** "Find all companies with 'Tech' in their name"
**Claude will:**
1. Use `search-companies` with query: `name:"Tech*"`
2. Return list of matching companies
---
**You:** "Get details for company 98765"
**Claude will:**
1. Use `get-company-details` to retrieve company information
2. Display company profile including contacts and relationships
---
### Getting Contact Information
**You:** "What email addresses do we have for candidate 12345?"
**Claude will:**
1. Use `get-person-emails` to retrieve all email addresses
2. Display the email addresses with their types
---
**You:** "Get phone numbers for candidate 12345"
**Claude will:**
1. Use `get-person-phones` to retrieve all phone numbers
2. Display phone numbers with their types
---
### Reference Data
**You:** "What activity types are available in Loxo?"
**Claude will:**
1. Use `get-activity-types` to retrieve the list
2. Display all available activity types with their IDs
---
**You:** "Who are the users in our agency?"
**Claude will:**
1. Use `list-users` to get agency users
2. Display user list with names and emails
---
## Available Tools
The server provides the following tools for AI assistants:
### Activity & Event Management
- `get-activity-types` - List available activity types
- `get-todays-tasks` - Get scheduled items (supports date filtering)
- `schedule-activity` - Create future person events
- `log-activity` - Log completed person events
### Candidate/People Management
- `search-candidates` - Search using Lucene syntax with complex multi-criteria queries (scroll_id pagination, returns skillsets and tags in results, 100 results per page default)
- `get-candidate` - Get full candidate profile
- `get-person-emails` - Get all email addresses
- `get-person-phones` - Get all phone numbers
- `list-person-job-profiles` - List work history
- `get-person-job-profile-detail` - Get specific job details
- `list-person-education-profiles` - List education history
- `get-person-education-profile-detail` - Get specific education details
### Job Management
- `search-jobs` - Search jobs (page-based pagination)
- `get-job` - Get full job details
### Company Management
- `search-companies` - Search companies (scroll_id pagination)
- `get-company-details` - Get company profile
### User Management
- `list-users` - List agency users
## Development
### Local Development
```bash
# Run in development mode with watch mode
npm run dev
# Build the project
npm run build
# Start the server
npm start
```
### Docker Development
```bash
# 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
```
## Type Safety
The server uses Zod for runtime type validation of:
- Environment variables
- Tool input parameters
- API responses
## Error Handling
The server includes comprehensive error handling for:
- Environment validation
- API request failures
- Invalid tool parameters
- Unknown tool requests
## Architecture
- Built using the Model Context Protocol SDK
- Communicates over stdio for seamless integration with AI assistants
- Uses TypeScript for type safety and better developer experience
- Implements RESTful API calls to Loxo's platform (API v1.3.1)
- All endpoints verified against official Loxo OpenAPI specification
## Implementation Notes
### Recent Changes
- **Removed non-existent endpoints:** Tools for `spark-search-activity-types`, `get-call-queue`, `add-to-call-queue`, and `add-note` have been removed as these endpoints don't exist in the Loxo API
- **Fixed activity endpoints:** `schedule-activity` and `log-activity` now correctly use the `/person_events` endpoint
- **Fixed tasks endpoint:** `get-todays-tasks` now uses `/schedule_items` endpoint
- **Fixed jobs search:** Now uses correct `/jobs` endpoint with page-based pagination (not scroll_id)
### Pagination
- **People/Companies/Events:** Use `scroll_id` cursor-based pagination
- **Jobs:** Use `page` and `per_page` offset-based pagination
### Activity/Event System
Activities in Loxo are managed through the `person_events` API:
- Scheduled activities use `created_at` with a future timestamp
- Logged activities use current timestamp (no `created_at` parameter)
- Events can be associated with a person, job, and/or company
### API Request Format
Most POST/PUT requests use `application/x-www-form-urlencoded` with field names in bracket notation:
- Example: `person_event[activity_type_id]=3`
- Example: `person_event[notes]=Great candidate`
