Viterbit MCP Server

A Model Context Protocol (MCP) server that provides Claude and other MCP-compatible clients with access to Viterbit recruitment API functionality.

Overview

This MCP server exposes comprehensive Viterbit API operations including candidate management, job operations, and candidature (application) handling. It allows Claude to interact with your Viterbit recruitment system autonomously.

Features

🧑‍💼 Candidate Management

• Search candidates by email address
• Get detailed candidate information including custom fields and addresses
• Update candidate data (Discord ID, subscription status, stage information)
• Filter candidates with enriched data for reporting
• 🆕 Search subscribers with advanced filtering by activity status, coach, mobility, etc.
• 🆕 Get candidate counts efficiently for statistical queries without loading all data

💼 Job Management

• Retrieve job details with comprehensive information
• Access job custom fields and company information

📋 Candidature (Application) Management

• Find active applications for any candidate
• Disqualify applications individually or in bulk
• Manage candidature lifecycle with proper reasons and timestamps

🛠️ Utility Functions

• Get custom field definitions to understand Viterbit schema
• Check candidate eligibility for reports and filtering
• Access department and location mappings
• Extract specific data from custom fields

Installation

1. Clone or copy the mcp_viterbit directory to your desired location
2. Install dependencies:

   cd mcp_viterbit
   pip install -r requirements.txt
   

3. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your Viterbit API key
   

Configuration

Required Environment Variables

• VITERBIT_API_KEY: Your Viterbit API key (required)

Optional Environment Variables

If you're using a different Viterbit instance with different custom field IDs, you can override them:

• DISCORD_ID_QUESTION_ID
• SUSCRIPTOR_QUESTION_ID
• CUSTOM_FIELD_STAGE_NAME_ID
• CUSTOM_FIELD_STAGE_DATE_ID
• CUSTOM_FIELD_SIN_DISCORD_ID
• CUSTOM_FIELD_NOMBRE_EMPRESA_ID
• GARANTIA_100_DIAS_ID
• ACTIVO_INACTIVO_ID

Usage

Running the Server

To run the MCP server directly:

cd mcp_viterbit
python -m server

Claude Desktop Integration

To integrate with Claude Desktop, add this configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "viterbit": {
      "command": "/path/to/mcp_viterbit/.venv/bin/python",
      "args": ["/path/to/mcp_viterbit/server.py"],
      "env": {
        "VITERBIT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Important: Use the full path to your virtual environment's Python interpreter and replace /path/to/mcp_viterbit/ with the actual path to your server directory.

Available Tools

Candidate Management

search_candidate

Search for a candidate by email address.

• Input: email (string)
• Output: Basic candidate info (ID, name, email, phone)

get_candidate_details

Get comprehensive candidate information.

• Input: candidate_id (string)
• Output: Full candidate details including custom fields

get_candidate_with_filters

Get candidate with enriched filtering data.

• Input: email (string)
• Output: Candidate data optimized for reporting/filtering

update_candidate_discord_id

Update candidate's Discord username.

• Input: candidate_id (string), discord_id (string)
• Output: Success confirmation

update_candidate_subscription

Update subscription status.

• Input: candidate_id (string), is_subscriber (boolean, default: true)
• Output: Success confirmation

update_candidate_stage

Update candidate's stage and date.

• Input: email (string), stage_name (string)
• Output: Success confirmation

search_subscribers 🆕

Search for candidates who are subscribers with advanced filtering options.

• Input: is_subscriber (boolean, default: true), activity_status (string, optional), page (number), page_size (number)
• Output: Enhanced format with summary metadata, filters applied, and candidate data
• Features: Returns total count, pagination info, and filtered results

get_candidate_count 🆕

Get total count of candidates matching specific criteria efficiently.

• Input: Multiple optional filters including is_subscriber, activity_status, coach, has_driving_license, national_mobility, has_experience
• Output: Total count with applied filters summary
• Performance: Fast operation using minimal data transfer (page_size=1)

Job Management

get_job_details

Get comprehensive job information.

• Input: job_id (string)
• Output: Full job details including custom fields

Candidature Management

find_active_candidatures

Find all active applications for a candidate.

• Input: email (string)
• Output: List of active candidatures

disqualify_candidature

Disqualify a specific application.

• Input: candidature_id (string), reason (string, default: "Baja Servicio")
• Output: Success status

disqualify_all_candidatures

Disqualify ALL active applications for a candidate.

• Input: email (string)
• Output: Detailed results including counts and errors

Utility Tools

get_custom_fields_definitions

Get all custom field schemas.

• Input: None
• Output: Custom field definitions

check_candidate_eligibility

Check if candidate should be included in reports.

• Input: viterbit_data (object)
• Output: Eligibility status and reason

get_department_location_mappings

Get department and location ID mappings.

• Input: None
• Output: Department and location mappings

extract_discord_username

Extract Discord username from custom fields.

• Input: custom_fields (array)
• Output: Discord username

Example Usage with Claude

Once configured in Claude Desktop, you can use natural language to interact with Viterbit:

Basic Operations

"Find me the candidate with email john.doe@example.com and show me their details"

"Update candidate ID 12345's Discord username to 'johndoe_discord'"

"Show me all active job applications for sara.smith@example.com"

"Disqualify all applications for candidate mike.jones@example.com because they unsubscribed"

"Get the details for job ID 67890 including custom fields"

🆕 Advanced Subscriber & Counting Queries

"How many active subscribers do we have?"
→ Uses get_candidate_count with subscriber and activity filters

"Show me 10 inactive subscribers"
→ Uses search_subscribers with activity_status: "Inactivo"

"How many candidates have a driving license?"
→ Uses get_candidate_count with has_driving_license: "Sí"

"Find subscribers assigned to coach Alexia"
→ Uses search_subscribers with coach filter

"What's the total number of candidates willing to travel nationally?"
→ Uses get_candidate_count with national_mobility: "Sí"

"Show me 5 subscribers and tell me the total count"
→ Uses search_subscribers which returns both data and total in summary

Custom Field Queries

"Show me all available custom fields and their IDs"
→ Uses get_custom_fields_definitions

"How many candidates need personalized follow-up?"
→ Uses custom field filtering capabilities

Error Handling

The server includes comprehensive error handling:

• API Errors: Viterbit API errors are caught and reported clearly
• Validation: Input parameters are validated before API calls
• Logging: Detailed logging for debugging and monitoring
• Graceful Failures: Tools return informative error messages instead of crashing

Security

• API Key Protection: API keys are loaded from environment variables
• No Data Storage: The server doesn't store or cache any sensitive data
• Minimal Permissions: Only requires Viterbit API access

Troubleshooting

Common Issues

1. "Viterbit API key is required"

   • Ensure VITERBIT_API_KEY is set in your environment or .env file

2. "Connection timeout"

   • Check your internet connection and Viterbit API status

3. "Candidate not found"

   • Verify the email address exists in Viterbit
   • Check for typos in email addresses

4. "Custom field errors"

   • Ensure your Viterbit instance uses the default custom field IDs
   • Override with correct IDs in environment variables if needed

Debugging

Enable debug logging by setting the logging level:

import logging
logging.getLogger().setLevel(logging.DEBUG)

Development

The server is built with:

• MCP SDK: For Model Context Protocol implementation
• httpx: For async HTTP requests to Viterbit API
• python-dotenv: For environment variable management

Project Structure

mcp_viterbit/
├── __init__.py           # Package initialization
├── server.py             # Main MCP server implementation
├── viterbit_client.py    # Viterbit API client with enhanced filtering
├── tools.py              # MCP tool definitions (16 tools total)
├── config.py             # Configuration and custom field ID mappings
├── requirements.txt      # Python dependencies
├── test_tools.py         # Test script for functionality verification
├── .env                  # Environment variables (with your API key)
└── README.md             # This documentation

Key Features Added in Latest Version

• 🔢 Statistical Queries: Fast candidate counting without data transfer overhead
• 🎯 Advanced Filtering: Search by subscription, activity, coach, mobility, experience, driving license
• 📊 Enhanced Metadata: All searches now return total counts, pagination info, and applied filters
• ⚡ Performance Optimized: Counting operations use minimal bandwidth (page_size=1)
• 🗂️ Custom Field Integration: Direct integration with all 27 Viterbit custom fields

License

This project was generated by Claude Code for use with Viterbit recruitment systems.

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review the logs for detailed error messages
3. Ensure your Viterbit API key has the necessary permissions
4. Verify your Viterbit instance configuration matches the expected field IDs