Mcp Factorial

MCP FactorialHR

> The definitive Model Context Protocol server for FactorialHR

[](https://opensource.org/licenses/MIT) [](https://github.com/t4dhg/mcp-factorial/actions/workflows/ci.yml) [](https://codecov.io/gh/t4dhg/mcp-factorial) [](https://codecov.io/gh/t4dhg/mcp-factorial) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://www.npmjs.com/package/@t4dhg/mcp-factorial) [](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 for compliance
• 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 117 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, getwithemployee, byjobrole, byjoblevel | | factorial_time_off | Leave management | 10 actions | | factorial_attendance | Shift management | list, get, create, update, delete | | factorial_documents | Document management | 8 actions (downloads require OAuth2 - see below) | | factorial_job_catalog | Job roles/levels | listroles, getrole, 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:

// 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' });

117 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 | listleaves, getleave, listtypes, gettype, listallowances, create, update, cancel, approve, reject | | Attendance | list, get, create, update, delete | | 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 | listroles, getrole, listlevels (read-only) | | Contracts | list, getwithemployee, byjobrole, byjoblevel (read-only) |

5 MCP Resources

| Resource URI | Description | | --------------------------------- | -------------------------------------------------- | | factorial://org-chart | Complete organizational hierarchy (Markdown) | | factorial://employees/directory | Employee directory by team (Markdown) | | factorial://locations/directory | Location directory with employee counts (Markdown) | | factorial://timeoff/policies | All leave types and policies (JSON) | | factorial://teams/{team_id} | Team details with member list (JSON, templated) |

4 MCP Prompts

| Prompt | Description | | ----------------------- | ----------------------------------------------------------------- | | onboard-employee | Generate personalized onboarding checklists | | analyze-org-structure | Analyze org structure (reporting lines, team sizes, distribution) | | timeoff-report | Generate time off reports by team or date range | | team-document-summary | Summarize documents across a team (certifications, payslips, etc) |

Architecture Features

• Safety Guardrails: High-risk operations (terminate, delete) marked for confirmation
• Audit Logging: All write operations logged with timestamps and context
• Caching: In-memory TTL-based caching (configurable by resource type)
• Pagination: All list operations support pagination
• Retry Logic: Exponential backoff with rate limit handling
• Validation: Runtime validation with Zod schemas

Quick Start

1. Add to your MCP configuration

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

2. Set your API key

Create a .env file in your project root:

FACTORIAL_API_KEY=your-api-key-here

Or pass it directly in the MCP config:

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"],
      "env": {
        "FACTORIAL_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Start using it!

Once configured, ask Claude things like:

• "Who's on the Engineering team?"
• "Create a new employee John Smith"
• "Approve the pending time off request for employee 42"
• "Create a new project called Q1 Marketing Campaign"
• "Enroll Sarah in the Leadership Training program"
• "Show me all open job postings"
• "What candidates applied for the Senior Developer position?"

Getting an API Key

You'll need a FactorialHR API key to use this MCP server. Here's how to get one:

1. Log in to FactorialHR as an administrator
2. Go to Settings → API keys
3. Click the "New API key" button
4. Give your key a descriptive name (e.g., "Claude Code" or "MCP Server")
5. Click Create - your API key will be displayed
6. Copy the key immediately - it's only shown once and cannot be retrieved later
7. Add the key to your .env file or MCP configuration

> Important: API keys have full access to your FactorialHR data and never expire. Store them securely, never commit them to version control, and rotate them periodically.

OAuth2 Setup (Required for Document Downloads)

Document download actions (download_payslips, download) require OAuth2 authentication. This is a Factorial API limitation - the download endpoint does not accept API key authentication.

> Note: You need admin access in Factorial to create OAuth applications.

Step 1: Create an OAuth2 Application

1. Go to: https://api.factorialhr.com/oauth/applications
2. Click "New application"
3. Fill in:

• Redirect URI: http://localhost:8080/callback (or any URL you can access)
• Confidentiality: Yes (server application)
• Scopes: Select the scopes you need:
• Required for downloads: Documents, Employees
• Recommended for full MCP functionality: Contracts, Payroll, Payroll supplements, Time off, Shift management, Trainings, Recruitment, Company locations, Job catalog

1. Save and note your Client ID and Client Secret

Step 2: Get Authorization Code

Open this URL in your browser (replace YOUR_CLIENT_ID):

https://api.factorialhr.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8080/callback&response_type=code

• Log in and authorize the app
• You'll be redirected to your callback URL with ?code=AUTHORIZATION_CODE
• Copy that code from the URL (it expires quickly, so proceed to step 3 immediately)

Step 3: Exchange Code for Tokens

Run this curl command (replace placeholders):

curl -X POST 'https://api.factorialhr.com/oauth/token' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'code=AUTHORIZATION_CODE' \
  -d 'grant_type=authorization_code' \
  -d 'redirect_uri=http://localhost:8080/callback'

You'll get a response with access_token and refresh_token. Save the refresh_token.

Step 4: Configure MCP Server

Add OAuth2 credentials to your MCP configuration:

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"],
      "env": {
        "FACTORIAL_API_KEY": "your-api-key",
        "FACTORIAL_OAUTH_CLIENT_ID": "your-client-id",
        "FACTORIAL_OAUTH_CLIENT_SECRET": "your-client-secret",
        "FACTORIAL_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Or add to your .env file:

FACTORIAL_API_KEY=your-api-key
FACTORIAL_OAUTH_CLIENT_ID=your-client-id
FACTORIAL_OAUTH_CLIENT_SECRET=your-client-secret
FACTORIAL_OAUTH_REFRESH_TOKEN=your-refresh-token

Important Notes

• Refresh tokens expire after 1 week - you'll need to repeat steps 2-3 if it expires
• The MCP server automatically refreshes access tokens using the refresh token
• If document downloads suddenly stop working, your refresh token has likely expired

Use Cases

For Managers

• Create and manage team structures
• Approve or reject time off requests
• Assign employees to projects
• Track project time records
• Monitor training enrollments

For HR

• Onboard new employees with full data entry
• Manage job postings and recruiting pipeline
• Track candidate applications through hiring stages
• Generate org structure analysis
• Manage training programs and enrollments

For Developers

• Build AI workflows that need employee context
• Create custom Claude integrations
• Automate HR processes with AI assistance
• Generate reports and analytics

Configuration Options

| Environment Variable | Description | Default | | ------------------------------- | ------------------------------------ | ------------ | | FACTORIAL_API_KEY | Your FactorialHR API key | Required | | FACTORIAL_API_VERSION | API version | 2025-10-01 | | FACTORIAL_TIMEOUT_MS | Request timeout (ms) | 30000 | | FACTORIAL_MAX_RETRIES | Max retry attempts | 3 | | DEBUG | Enable debug logging | false | | FACTORIAL_OAUTH_CLIENT_ID | OAuth2 client ID (for downloads) | - | | FACTORIAL_OAUTH_CLIENT_SECRET | OAuth2 client secret (for downloads) | - | | FACTORIAL_OAUTH_REFRESH_TOKEN | OAuth2 refresh token (for downloads) | - |

Safety & Security

High-Risk Operations

The following operations are marked as high-risk and require explicit confirmation (confirm: true):

• factorial_employees({ action: 'terminate' }) - Terminates an employee
• factorial_teams({ action: 'delete' }) - Permanently deletes a team
• factorial_locations({ action: 'delete' }) - Permanently deletes a location
• factorial_projects({ action: 'delete' }) - Permanently deletes a project
• factorial_ats({ action: 'delete_candidate' }) - Permanently deletes a candidate

Read-Only Categories

Some categories are intentionally read-only for security:

• Payroll: Supplements, tax identifiers, family situations
• Documents: Folder and document metadata (download tools available for payslips and documents)
• Contracts: Historical contract data

Response Optimization

Document and contract list operations return summary format by default to prevent token overflow:

Documents (factorial_documents({ action: 'list' })):

• Returns: id, name, folder_id, employee_id, mime_type (5 fields)
• Default limit: 100 documents per page
• For full details: Use factorial_documents({ action: 'get', id: X }) for complete metadata

Contracts (factorial_contracts({ action: 'list' })):

• Returns: id, employee_id, job_title, effective_on (4 fields)
• Default limit: 100 contracts per page

All list operations accept page and limit parameters for pagination control.

Audit Logging

All write operations (create, update, delete, approve, reject) are logged with:

• Timestamp
• Operation type
• Entity type and ID
• Changes made

Development

# Clone the repository
git clone https://github.com/t4dhg/mcp-factorial.git
cd mcp-factorial

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Format
npm run format

# Run locally
FACTORIAL_API_KEY=your-key npm start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

Project Structure

The codebase is organized into domain-based modules for maintainability:

src/
├── schemas/           # Zod schemas by domain
│   ├── employees.ts   # Employee, Team, Location, Contract schemas
│   ├── time-off.ts    # Leave, LeaveType, Allowance, Shift schemas
│   ├── projects.ts    # Project, Task, Worker, TimeRecord schemas
│   ├── training.ts    # Training, Session, Membership schemas
│   ├── ats.ts         # JobPosting, Candidate, Application schemas
│   └── ...
├── api/               # API functions by domain
│   ├── employee

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [t4dhg](https://github.com/t4dhg)
- **Source:** [t4dhg/mcp-factorial](https://github.com/t4dhg/mcp-factorial)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/@t4dhg/mcp-factorial

Install and usage instructions live in the source repository linked above.