Factorial

You are using an MCP server that provides FactorialHR data to AI assistants with safe, auditable access. This server enables you to manage employees, teams, time off, projects, training, recruiting, and more through structured tool actions while enforcing guardrails and logging for compliance.

How to use

You interact with the MCP server through an MCP client or integration that can call categorized actions. Start by discovering what categories and actions are available, then perform CRUD operations to manage employees, teams, locations, time off, projects, training, and recruiting. High‑risk actions require explicit confirmation, and all write operations are audited for traceability.

Typical workflows include listing entities, creating new records, updating existing items, approving or cancelling workflows, and retrieving related data aggregated from multiple sources. You can also leverage predefined resources and prompts to analyze organizational structures, onboard employees, or generate reports. Always ensure you have a valid API key and, if you need document downloads, OAuth2 credentials configured for the downloads path.

How to install

Prerequisites: Node.js and npm installed on your machine. You will also need access to a FactorialHR API key and, for downloads, OAuth2 credentials.

Step 1: Add the MCP server to your configuration.

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"]
    }
  }
}

Additional configuration and usage notes

Configure your FactorialHR API key and OAuth2 credentials to enable full functionality, including document downloads. The server supports in‑memory caching, pagination, validation with Zod schemas, and audit logging for all write operations.

Example environment variables you may configure (placeholders shown):

FACTORIAL_API_KEY=your-api-key
FACTORIAL_API_VERSION=2025-10-01
FACTORIAL_TIMEOUT_MS=30000
DEBUG=false
FACTORIAL_OAUTH_CLIENT_ID=your-client-id
FACTORIAL_OAUTH_CLIENT_SECRET=your-client-secret
FACTORIAL_OAUTH_REFRESH_TOKEN=your-refresh-token

Security and governance

High‑risk operations such as terminating employees, deleting teams or locations, deleting projects, or removing candidates are guarded by explicit confirmations. Audit logging records every write action with timestamps and context to support compliance needs.

Available tools

factorial_discover

Discover available categories and actions within the MCP server

factorial_employees

Employee management actions including list, get, search, create, update, and terminate

factorial_teams

Team management actions including list, get, create, update, delete

factorial_locations

Location management actions including list, get, create, update, delete

factorial_time_off

Leave management actions including create, update, cancel, approve, and reject

factorial_attendance

Shift management actions including list, get, create, update, delete

factorial_documents

Document management actions including 8 operations with downloads requiring OAuth2

factorial_job_catalog

Job roles and levels management including list_roles, get_role, list_levels

factorial_projects

Project management actions including projects, tasks, workers, and time entries

factorial_training

Training management actions including trainings, sessions, enrollments

factorial_work_areas

Work area management actions including list, get, create, update, archive, unarchive

factorial_ats

Applicant tracking actions including 17 operations for recruiting

factorial_payroll

Payroll data access including supplements, tax identifiers, and family situations (read-only)