pepuscz/recruitee-mcp-server

Recruitee MCP Server

A Model Context Protocol (MCP) server for the Recruitee API that enables extraction of candidate profiles from recruitment pipelines. Features clean, purpose-built functions optimized for different use cases: basic overviews, LLM evaluation, and detailed analysis.

Features

• LLM Evaluation Optimized: Clean, bias-free candidate data perfect for AI analysis
• PDF Text Extraction: Automatic CV and cover letter extraction using pdfplumber
• Screening Questions: Clean Q&A format for easy evaluation
• Efficient Processing: CV text processing configurable for performance optimization
• Advanced Search: Multi-criteria candidate filtering
• Notes & Ratings: Separate access to evaluator feedback

Available Tools

Core Tools

1. get_candidates_from_pipeline_for_evaluation - Recommended for LLM analysis - Clean evaluation data
2. get_candidate_profile - Complete candidate profile with all administrative data
3. search_candidates - Advanced candidate search with filtering
4. get_candidate_notes - Access notes, ratings, and evaluator feedback
5. list_jobs - List all available jobs/pipelines
6. get_job_details - Get detailed job information

Tool Details

get_candidates_from_pipeline_for_evaluation(job_id, stage_filter=None, include_full_cv=False) ⭐ Recommended

LLM evaluation optimized: Clean, bias-free data perfect for candidate analysis.

Parameters:

• job_id: The job/pipeline ID (required)
• stage_filter: Optional stage name filter
• include_full_cv: Whether to include full CV text (default: False). Set to True to include full CV text - basic CV metadata always included.

Returns:

• CV full text extraction (PDF → text) - optional based on include_full_cv parameter
• Clean screening questions: [{"question": "...", "answer": "...", "question_type": "text"}]
• Flattened skills array: ["JavaScript", "React", "Node.js"]
• Structured experience: [{"company": "...", "title": "...", "description": "..."}]
• Cover letter text
• Basic facts only: has_degree, total_screening_questions, answered_questions

get_candidate_profile(candidate_id)

Complete candidate profile: All candidate data including contact info, CV, cover letter, experience, and all custom fields.

• Returns: Full profile with contact info, CV/cover letter PDFs, custom fields, and full PDF text extraction
• Use case: Individual detailed review, contact information access, complete administrative data
• Performance: 🐌 Slow (comprehensive data + PDF processing)

search_candidates(job_ids=None, stage_names=None, status=None, has_cv=None, has_cover_letter=None, limit=50, offset=0)

Advanced search: Multi-criteria candidate filtering across all candidates.

• Returns: Filtered candidate list with pagination support
• Use case: Finding candidates by specific criteria, bulk operations
• Performance: 🔄 Medium (client-side filtering)

get_candidate_notes(candidate_id)

Evaluator feedback: Access to ratings, notes, and comments.

• Returns: Notes, ratings, comments from recruiters/interviewers
• Use case: Review evaluator feedback and scoring

list_jobs() and get_job_details(job_id)

Job management: List available jobs and get detailed job information.

• Returns: Job listings with metadata, stages, and requirements
• Use case: Discovering available positions, understanding job requirements

Installation

# Install from source
git clone [repository-url]
cd recruitee-mcp-server
pip install -e .

Configuration

export RECRUITEE_API_TOKEN="your-api-token" 
export RECRUITEE_COMPANY_ID="your-company-id"

Usage

Recommended Workflow

# 1. Get clean evaluation data for LLM analysis (CV text excluded by default)
evaluation_data = get_candidates_from_pipeline_for_evaluation("job_id")

# 1a. For detailed analysis including CV text
evaluation_data = get_candidates_from_pipeline_for_evaluation("job_id", include_full_cv=True)

# 2. Get individual candidate details with full CV text (always included)
profile = get_candidate_profile("candidate_id")  # Complete administrative data

# 3. Review evaluator feedback separately  
notes = get_candidate_notes("candidate_id")

# 4. Get full administrative details only when needed (contact info, etc.)
full_profile = get_candidate_profile("candidate_id")  # Always returns full data

Function Comparison

MCP Integration

{
  "mcpServers": {
    "recruitee": {
      "command": "python", 
      "args": ["-m", "recruitee_mcp.server"],
      "env": {
        "RECRUITEE_API_TOKEN": "your-token",
        "RECRUITEE_COMPANY_ID": "your-company-id"
      }
    }
  }
}

Performance Tips

• Pipeline analysis: Use get_candidates_from_pipeline_for_evaluation() (clean, optimized data)
• Large datasets: Keep include_full_cv=False (default) to skip CV text processing for better performance
• Individual analysis: Use get_candidate_profile() for complete administrative data with contact info
• Evaluator feedback: Use get_candidate_notes() for ratings/comments

License

MIT License

💼 Perfect for AI-powered recruitment tools and LLM candidate evaluation systems.