Skip to content
MCP server

MCP FactorialHR

Full read-write MCP server for FactorialHR with 14 category tools and safety guardrails

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
12.0.0
Listing updated
today

Similar MCP servers

About MCP FactorialHR

MCP FactorialHR is an open-source MCP server for hiring and recruiting. It runs locally on your machine and is started by your AI client.

Rather than exposing over a hundred separate tools, the server groups operations into 14 category tools that take an action parameter, which the README says cuts context use by 88%. Categories include employees, teams, locations, contracts, time off, attendance, documents, job catalog, projects, training, work areas, ATS recruiting and read-only payroll. A discover tool lists the actions in each category.

Writes are logged with timestamps, and high-risk operations need explicit confirmation. Attendance covers clock in and out, gap checks and a whole month of working-hours logging, with records marked as entered through the API. Document downloads require OAuth2.

It runs over stdio from npm and needs a FactorialHR API key; the licence is MIT.

Install

Run in a terminal

claude mcp add mcp-factorial --env FACTORIAL_API_KEY='<FACTORIAL_API_KEY>' -- npx -y @t4dhg/mcp-factorial

Add to claude_desktop_config.json

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

Add to ~/.cursor/mcp.json

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

Add to .vscode/mcp.json

{
  "servers": {
    "mcp-factorial": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@t4dhg/mcp-factorial"
      ],
      "env": {
        "FACTORIAL_API_KEY": "<FACTORIAL_API_KEY>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Using several servers? Build one config file with the MCP config generator.

Configuration

  • FACTORIAL_API_KEYAPI key from FactorialHR (Settings > API Keys)Required
  • FACTORIAL_API_VERSIONAPI version (default: 2026-07-01)
  • FACTORIAL_TIMEOUT_MSRequest timeout in milliseconds (default: 30000)
  • FACTORIAL_MAX_RETRIESMaximum retry attempts (default: 3)
  • DEBUGEnable debug logging (default: false)

Tools this server provides (14)

Taken from the project documentation; the running server may differ.

factorial_discover
Lists categories and available actions.
factorial_employees
Employee list, get, search, create, update, terminate.
factorial_teams
Team management.
factorial_locations
Location management.
factorial_contracts
Contract and salary data.
factorial_time_off
Leave management.
factorial_attendance
Shifts, clock in and out, audit and log ranges.
factorial_documents
Document management.
factorial_job_catalog
Job roles and levels.
factorial_projects
Projects, tasks, workers and time.
factorial_training
Trainings, sessions and enrollments.
factorial_work_areas
Work area management.
factorial_ats
Applicant tracking.
factorial_payroll
Read-only payroll data.

What it does

Hierarchical tools
14 category tools with an action parameter instead of one tool per operation.
Full CRUD
Create, read, update and delete across major entities.
Safety guardrails
High-risk actions require explicit confirmation.
Audit logging
Write operations are logged with context.
Attendance tools
Clock in and out, audit gaps and log whole ranges.
Recruiting and training
ATS and training actions included.

Good for

  • Create a leave request from a chat message
  • Log a month of working hours
  • Search employees and review contracts
  • Review applicants in the ATS

Pricing

Open source

Requires a FactorialHR account

MCP FactorialHR FAQ

What do I need?

A FactorialHR API key set as FACTORIAL_API_KEY.

Can it change data?

Yes, with confirmations on high-risk operations; payroll is read-only.

What licence?

MIT.

How many operations?

The README cites 124 operations across 14 categories.

Is MCP FactorialHR free?

Yes. MCP FactorialHR is open source, so you can use and self-host it for free.

How do I add MCP FactorialHR to Claude Code?

Run this command in your terminal: claude mcp add mcp-factorial --env FACTORIAL_API_KEY='<FACTORIAL_API_KEY>' -- npx -y @t4dhg/mcp-factorial

What are the best alternatives to MCP FactorialHR?

The closest alternatives to MCP FactorialHR are Ha MCP, Concord MCP, Reactive Resume, note1 and Jira.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers