HRLab MCP Server

A Model Context Protocol (MCP) server for integrating with the HRLab API. This server provides comprehensive access to all HRLab endpoints for HR data management.

Features

This MCP server provides access to all HRLab API endpoints organized into categories:

Absences (4 tools)

• getAllVacations - Get all vacation records
• getAllSicknesses - Get all sickness records
• getAllTravels - Get all travel records
• getAllHomeOffices - Get all home office records

Organisation (11 tools)

• getAllUsers - Get all user records
• getAllDepartments - Get all department records
• getAllTeams - Get all team records
• getAllCompanies - Get all company records
• getAllAbsenceTypes - Get all absence type records
• getAllBranchOffices - Get all branch office records
• getAllCostUnits - Get all cost unit records
• getAllEquipments - Get all equipment records
• getAllProjects - Get all project records
• getAllQualificationTypes - Get all qualification type records
• getAllTasks - Get all task records

Remuneration (4 tools)

• getAllBonusTargets - Get all bonus target records
• getAllHourlyWages - Get all hourly wage records
• getAllPerks - Get all perk records
• getAllSalaryTypes - Get all salary type records

Family (3 tools)

• getAllChildren - Get all children records
• getAllMaternities - Get all maternity records
• getAllParentalLeaves - Get all parental leave records

Recruiting (4 tools)

• getAllAnnouncements - Get all job announcement records
• getAllCandidatures - Get all candidature records
• getAllCandidatureStatuses - Get all candidature status records
• getAllStatuses - Get all status records

UserData (5 tools)

• getAllAppointments - Get all appointment records
• getAllBankAccounts - Get all bank account records
• getAllCertificates - Get all certificate records
• getAllContactData - Get all contact data records
• getAllBudgets - Get all budget records

Benefits (3 tools)

• getAllBenefits - Get all benefit records
• getAllCapitalFormingBenefits - Get all capital forming benefit records
• getAllCompanyPensions - Get all company pension records

Installation

Via NPX (Recommended)

npx @asanstefanski/hrlab-mcp-server

Via NPM Global Install

npm install -g @asanstefanski/hrlab-mcp-server
hrlab-mcp-server

Local Development

1. Clone and install dependencies:

   git clone https://github.com/asanstefanski/hrlab-mcp-server.git
   cd hrlab-mcp-server
   npm install

2. Build the project:

   npm run build

3. Start the server:

   npm start

Configuration

The server requires an HRLab API token to authenticate with the HRLab API. You can obtain this token from your HRLab account settings.

Set the environment variable:

export HRLAB_API_TOKEN="your-hrlab-api-token"

Or create a .env file in your project root:

HRLAB_API_TOKEN=your-hrlab-api-token

Development

• Watch mode for development:

  npm run dev

• Clean build directory:

  npm run clean

API Features

• Automatic pagination - Handles large datasets by automatically fetching all pages
• Rate limiting - Respects HRLab's rate limits (60 requests per minute)
• Filtering support - Most endpoints support filtering by user ID, date ranges, and other parameters
• Error handling - Comprehensive error handling for API failures
• TypeScript support - Full TypeScript interfaces for all HRLab data types

Usage with Claude Code

After setting up the server, you can use it with Claude Code or other MCP clients:

1. Configure your MCP client to connect to this server
2. Use the available tools to query HRLab data
3. All tools support optional filtering parameters

Example Tool Usage

// Get all vacations for the last 3 months
getAllVacations({
  start_date: "01-04-2024" // DD-MM-YYYY format
})

// Get all users in a specific department
getAllUsers({
  department_id: "123"
})

// Get all appointments for a specific user
getAllAppointments({
  user_id: "456",
  start_date: "01-07-2024",
  end_date: "31-07-2024"
})

Rate Limiting

The server implements rate limiting to comply with HRLab's API limits:

• Maximum 60 requests per minute
• 1 second minimum interval between requests
• Automatic retry handling

Error Handling

The server includes comprehensive error handling for:

• Invalid API tokens
• Network connectivity issues
• API rate limit exceeded
• Invalid parameter values
• Server errors

License

MIT