# MCP FactorialHR

> MCP FactorialHR is an open-source MCP server for hiring and recruiting. Full read-write MCP server for FactorialHR with 14 category tools and safety guardrails. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/t4dhg/mcp-factorial
- **MCP Registry name:** io.github.t4dhg/mcp-factorial
- **Categories:** [hiring and recruiting](https://ai-powered.com/categories/hiring-and-recruiting), [productivity](https://ai-powered.com/categories/productivity)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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.

## Alternatives

- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [Reactive Resume](https://ai-powered.com/mcp/reactive-resume): Reactive Resume is an open-source MCP server for hiring and recruiting.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [Jira](https://ai-powered.com/mcp/jira): Jira is a freemium MCP server for productivity.
- [Google Workspace MCP](https://ai-powered.com/mcp/google-workspace-mcp-2): Google Workspace MCP is an MCP server for productivity.
- [InviteKit Calendar Files](https://ai-powered.com/mcp/invitekit-calendar-files): InviteKit Calendar Files is an MCP server for files and documents.
- [Zovo Org Chart Maker](https://ai-powered.com/mcp/zovo-org-chart-maker): Zovo Org Chart Maker is an MCP server for productivity.

---
Source: https://ai-powered.com/mcp/mcp-factorialhr
