mcp-factorial

<p align="center">
  <img src="https://raw.githubusercontent.com/t4dhg/mcp-factorial/main/assets/factorial-logo.svg" alt="FactorialHR" height="48">
</p>

# MCP FactorialHR

> **The definitive Model Context Protocol server for [FactorialHR](https://factorialhr.com)**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/t4dhg/mcp-factorial/actions/workflows/ci.yml/badge.svg)](https://github.com/t4dhg/mcp-factorial/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/t4dhg/mcp-factorial/branch/main/graph/badge.svg)](https://codecov.io/gh/t4dhg/mcp-factorial)
[![bundle](https://codecov.io/gh/t4dhg/mcp-factorial/graph/bundle/mcp-factorial/badge.svg)](https://codecov.io/gh/t4dhg/mcp-factorial)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg)](https://nodejs.org/)
[![npm version](https://img.shields.io/npm/v/@t4dhg/mcp-factorial.svg)](https://www.npmjs.com/package/@t4dhg/mcp-factorial)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

A comprehensive Model Context Protocol (MCP) server that provides AI assistants like Claude with full access to FactorialHR. Manage employees, teams, time off, projects, training, recruiting, and more - all with built-in safety guardrails.

## Why This MCP Server?

- **Context-Optimized**: 14 hierarchical tools (117 operations) with 88% less context usage than individual tools
- **Full CRUD Operations**: Create, read, update, and delete across all major entities
- **Safety Guardrails**: High-risk operations require explicit confirmation
- **Audit Logging**: All write operations are logged with timestamps and context for debugging
- **Enterprise Ready**: Built for companies who need AI integration with proper controls

## Features

### Hierarchical Tool Discovery (v8.0.0+)

The MCP server uses a hierarchical tool structure for optimal context usage. Instead of 124 individual tools, you get 14 category-based tools with an `action` parameter.

| Tool                    | Description                   | Actions                                            |
| ----------------------- | ----------------------------- | -------------------------------------------------- |
| `factorial_discover`    | Discover available categories | -                                                  |
| `factorial_employees`   | Employee management           | list, get, search, create, update, terminate       |
| `factorial_teams`       | Team management               | list, get, create, update, delete                  |
| `factorial_locations`   | Location management           | list, get, create, update, delete                  |
| `factorial_contracts`   | Contract/salary data          | list, get_with_employee, by_job_role, by_job_level |
| `factorial_time_off`    | Leave management              | 10 actions                                         |
| `factorial_attendance`  | Shifts and registro horario   | 14 actions incl. clock_in, audit, log_range        |
| `factorial_documents`   | Document management           | 8 actions (downloads require OAuth2 - see below)   |
| `factorial_job_catalog` | Job roles/levels              | list_roles, get_role, list_levels                  |
| `factorial_projects`    | Project management            | 16 actions for projects, tasks, workers, time      |
| `factorial_training`    | Training management           | 12 actions for trainings, sessions, enrollments    |
| `factorial_work_areas`  | Work area management          | list, get, create, update, archive, unarchive      |
| `factorial_ats`         | Applicant tracking            | 17 actions for recruiting                          |
| `factorial_payroll`     | Payroll data (read-only)      | 6 actions                                          |

**Example Usage:**

```typescript
// List all employees
factorial_employees({ action: 'list', page: 1, limit: 50 });

// Get a specific employee
factorial_employees({ action: 'get', id: 123 });

// Search employees
factorial_employees({ action: 'search', query: 'john' });

// Create a leave request
factorial_time_off({
  action: 'create',
  employee_id: 123,
  leave_type_id: 1,
  start_on: '2026-02-01',
  finish_on: '2026-02-05',
});

// Discover available actions for a category
factorial_discover({ category: 'employees' });
```

### 124 Operations Across 14 Categories

| Category        | Operations                                                                                                                                |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Employees**   | list, get, search, create, update, terminate                                                                                              |
| **Teams**       | list, get, create, update, delete                                                                                                         |
| **Locations**   | list, get, create, update, delete                                                                                                         |
| **Time Off**    | list_leaves, get_leave, list_types, get_type, list_allowances, create, update, cancel, approve, reject                                    |
| **Attendance**  | list, get, create, update, delete, clock_in, clock_out, status, gaps, audit, log_range, log_days, list_edit_requests, create_edit_request |
| **Projects**    | 16 operations for projects, tasks, workers, time records                                                                                  |
| **Training**    | 12 operations for trainings, sessions, enrollments                                                                                        |
| **Work Areas**  | list, get, create, update, archive, unarchive                                                                                             |
| **ATS**         | 17 operations for job postings, candidates, applications, hiring stages                                                                   |
| **Payroll**     | list/get supplements, tax identifiers, family situations (read-only)                                                                      |
| **Documents**   | 8 operations for folders, documents, and downloads (⚠️ downloads require OAuth2)                                                          |
| **Job Catalog** | list_roles, get_role, list_levels (read-only)                                                                                             |
| **Contracts**   | list, get_with_employee, by_job_role, by_job_level (read-only)                                                                            |

### Attendance and Registro Horario

Factorial asks employees to record their working hours day by day. `factorial_attendance` lets Claude do that, for one day or for a whole month, and for any employee the API key can see.

Times are `HH:MM` in the company's local time, exactly as Factorial shows them; Factorial applies them in the company zone and the server never converts between zones. Records written by this server carry `source: "api"`, so they are distinguishable from live clocks in Factorial's own activity log.

A write's **declared working time** (`date`, `clock_in`, `clock_out`) is independent of its **entry metadata**: Factorial stamps `created_at`, `updated_at` and `in_source`/`out_source` with when and how the record was entered, and those cannot be set or changed through the API. Every create, update, `clock_in`, `clock_out`, and every bulk preview and result, states the declared working time and says this once.

| Action                                      | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`                                    | Whether the employee is clocked in and since when. Always prints the configured identity.