Viterbit

Provides MCP access to Viterbit recruitment data for candidate, job, and candidature management.

python

0

GitHub Stars

python

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "techkampe-mcp_viterbit": {
      "command": "python",
      "args": [
        "-m",
        "server"
      ],
      "env": {
        "VITERBIT_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

You run a Viterbit MCP Server to give Claude and other MCP clients programmatic access to your Viterbit recruitment data. This server handles candidates, jobs, candidatures, and utility operations, letting you automate workflows, generate reports, and integrate Viterbit data into your MCP-enabled tools.

How to use

You use an MCP client to interact with the Viterbit MCP Server by calling a set of predefined tools. These tools let you search for candidates, view and update details, manage job data, handle applications, and run utility operations such as counting candidates or extracting custom field data. Start by configuring the MCP client with the server’s connection details, then perform actions like finding a candidate by email, retrieving detailed candidate information, or listing active candidatures. You can also integrate with Claude Desktop so natural language commands map to these tools.

How to install

Prerequisites: Python 3.x and pip are required to run the server. You should also have a working shell with access to install Python packages.

Clone or copy the MCP server package to your preferred location.
Install dependencies.

cd mcp_viterbit
pip install -r requirements.txt

Set up environment variables by copying the example and editing the API key.

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

Running the server

To run the MCP server directly from your environment, start in the server directory.

cd mcp_viterbit
python -m server

Claude Desktop Integration

Connect Claude Desktop to the MCP server by adding a configuration that points to the local Python runtime and the server module. The example uses a virtual environment’s Python interpreter and the server script, with the API key supplied via environment variables.

{
  "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"
      }
    }
  }
}

Configuration

Required environment variable: VITERBIT_API_KEY must be set to your Viterbit API key.

Optional overrides for custom field IDs in case you use a different Viterbit instance:

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

Security and troubleshooting

The server loads API keys from environment variables and does not store sensitive data. If you encounter issues, verify the API key is present and the Viterbit instance is reachable.

Common issues include missing API keys, timeouts, or candidate lookups failing due to mismatched emails. Check logs for details and ensure your environment variables are correctly set.

Development notes

The server is built with the MCP SDK and uses httpx for asynchronous HTTP requests to Viterbit, with python-dotenv for environment variable management. The project structure includes the main server, a Viterbit API client, tools definitions, and configuration mappings.

Available tools

search_candidate

Search for a candidate by email address and return basic candidate info (ID, name, email, phone).

get_candidate_details

Retrieve comprehensive candidate information including custom fields and addresses.

get_candidate_with_filters

Get a candidate with enriched filtering data for reporting and analysis.

update_candidate_discord_id

Update a candidate's Discord username.

update_candidate_subscription

Update a candidate's subscription status.

update_candidate_stage

Update a candidate's stage and the associated date.

search_subscribers

Find subscribers with advanced filtering and return data with total counts and pagination metadata.

get_candidate_count

Get total count of candidates matching criteria with minimal data transfer.

get_job_details

Retrieve detailed job information including custom fields.

find_active_candidatures

Find all active candidatures for a given candidate.

disqualify_candidature

Disqualify a specific candidature with a reason.

disqualify_all_candidatures

Disqualify all active candidatures for a candidate.

get_custom_fields_definitions

Return all custom field definitions.

check_candidate_eligibility

Determine if a candidate should be included in reports based on data.

get_department_location_mappings

Provide mappings for departments and locations.

extract_discord_username

Extract a Discord username from a candidate's custom fields.