# HR Partner MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI assistants
(Claude Desktop, Claude Code, ChatGPT, and any other MCP-compatible client) read and write data in
your [HR Partner](https://www.hrpartner.io) company using the
[HR Partner public API](https://developer.hrpartner.io).

Ask things like:

- "Who is on leave next week?"
- "List all employees in the London office who started this year"
- "Show me pending expense claims for the Warehouse department"
- "Create a new applicant for the Forklift Driver job and move them to the Interview stage"
- "What are the leave balances for employee EMP001?"

## Prerequisites

1. An active HR Partner subscription (trial or paid).
2. Your company **API key**: in HR Partner go to **Setup -> Configure -> Integrations**, switch on
   API access (it is off by default) and copy the key. Keep it secret; anyone with the key can read
   your company data.
3. Node.js 18 or newer.

## Disclaimer

This MCP server is an early Beta prototype, and is subject to change at any time without notice (including removal from this repository).

This MCP server may expose data to the user that could be private (i.e. contact details, salary information, Tax/SSN numbers etc.).  Please ensure that you write your own SKILL.md or adjust your prompts to prevent this server from exposing anything that is critical.

This MCP server also does not respect the Admin user permissions for certain Departments, Locations, Groups or module access like our actual platform does.  Once again, you may have to tailor your prompting or SKILL file to build in these restrictions yourselves.

Our support or development team **do not** provide support for anyone who may be using this MCP server, nor do we accept responsibility should there be any inadvertent access of sensitive information, or any data corruption caused as a result of using this server.

Please also be aware that using this MCP server will mean that returned data will be processed using third party LLMs that are outside the control of HR Partner, and we cannot restrict those third party LLMs from using your data for training purposes or other context within the LLM.

## Installation

```bash
npm install
npm run build
```

This produces `build/index.js`, which is the server entry point.

## Configuration

The server speaks MCP over **stdio** and needs your API key in the environment:

| Variable | Required | Description |
| -------- | -------- | ----------- |
| `HR_PARTNER_API_KEY` | Yes | Your HR Partner API key |
| `HR_PARTNER_API_BASE_URL` | No | API base URL, defaults to `https://api.hrpartner.io`. Must be an `https://` URL; `http://` is only accepted for localhost (e.g. testing against a local mock API) |
| `HR_PARTNER_READ_ONLY` | No | Set to `1`, `true` or `yes` to run in read-only mode: no write tools are registered, so the AI assistant can only read data |

### Claude Desktop

Add to `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hrpartner": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/build/index.js"],
      "env": {
        "HR_PARTNER_API_KEY": "paste-your-api-key-here"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

### Claude Code

```bash
claude mcp add hrpartner \
  --env HR_PARTNER_API_KEY=paste-your-api-key-here \
  -- node /absolute/path/to/mcp/build/index.js
```

### ChatGPT and other MCP clients

Any client that supports MCP stdio servers can use this server with the same building blocks:

- **Command:** `node`
- **Args:** `["/absolute/path/to/mcp/build/index.js"]`
- **Environment:** `HR_PARTNER_API_KEY=<your key>`

Refer to your client's documentation for where to register a local MCP server.

### Publishing / npx usage

If this package is published to npm (or installed from a git URL), clients can run it without a
local checkout:

```json
{
  "mcpServers": {
    "hrpartner": {
      "command": "npx",
      "args": ["-y", "hrpartner-mcp-server"],
      "env": { "HR_PARTNER_API_KEY": "paste-your-api-key-here" }
    }
  }
}
```

## Available tools

All tools map 1:1 to endpoints in the [HR Partner API reference](https://developer.hrpartner.io).
List tools return **all** matching records (the API does not paginate), so they accept a
`max_records` argument that truncates results client-side to keep AI context sizes manageable.

### Core
| Tool | Description |
| ---- | ----------- |
| `get_company` | Company name, subscription, employee counts, timezone; good connectivity test |
| `list_employees` | Employees with filters (department, location, status, dates, tags, reports-to, ...) |
| `get_employee` | Full employee record by code: contacts, addresses, tags, custom fields |
| `save_employee` | Create or update an employee (upsert by code), incl. custom fields, tags, contacts, addresses |
| `list_contacts` | Contact records across employees |
| `list_addresses` | Address records across employees |

### Employee records
`list_absences`, `list_assets`, `list_attachments`, `list_benefits`, `list_dependents`,
`list_education`, `list_grievances`, `list_interviews`, `list_notes`, `list_positions`,
`list_renewables`, `list_reviews`, `list_skills`, `list_training`

### Organisation
`list_goals`, `list_checklists`, `list_birthdays`, `list_anniversaries`,
`get_library_documents`, `get_library_categories`, `get_lookup` (valid filter values for 30 lists)

### Leave, time and money
`list_leave_requests`, `get_leave_request`, `list_leave_balances`,
`list_timesheets`, `get_timesheet`, `add_timeclock_entry` (writes a time entry),
`list_expenses` (detailed / summary / transaction reports), `list_projects`

### Performance and reminders
`list_performances` (optionally with form answers),
`list_reminders`, `get_reminder`, `update_reminder`, `delete_reminder`

### Status board
`list_status_board` (every employee's current status), `list_status_board_statuses` (valid status
values), `get_status_board_entry`, `save_status_board_entry` (set an employee's status)

### Recruitment
`list_jobs`, `get_job`, `list_applicants`, `get_applicant`, `save_applicant` (upsert by email),
`list_applications`, `get_application`, `save_application`, `get_application_stage_tracking`

## Security notes

- The API key grants full API access to your HR Partner company. Store it only in your local MCP
  client configuration, never commit it to source control, and regenerate it in HR Partner if you
  suspect it has leaked.
- Set `HR_PARTNER_READ_ONLY=1` to disable all write tools at startup (the tools are never
  registered, so the AI assistant cannot see or call them). Recommended unless you explicitly need
  the assistant to create or modify records.
- `HR_PARTNER_API_BASE_URL` is validated before any request is sent: only `https://` URLs (or
  `http://localhost`) are accepted, so the API key cannot be sent to a cleartext endpoint.
- API access is disabled by default in HR Partner and can be switched off at any time under
  **Setup -> Configure -> Integrations**.
- The server runs locally on your machine and communicates only with `https://api.hrpartner.io`.

## Development

```bash
npm run build     # compile TypeScript to build/
npm run dev       # watch mode
npm start         # run the server on stdio
```

Project layout:

```
src/
  index.ts             server bootstrap (stdio transport, server instructions)
  client.ts            HR Partner REST client (x-api-key auth, error mapping, timeouts)
  tools/
    helpers.ts         shared zod params, GET-tool registration, result formatting
    employees.ts       company, employees, contacts, addresses, save_employee
    submodules.ts      the 14 employee sub-module list endpoints
    org.ts             goals, checklists, birthdays, anniversaries, library, lookups
    misc.ts            reminders, leave, expenses, projects, performances
    recruitment.ts     jobs, applicants, applications, stage tracking
    statusboard.ts     status board entries and statuses
    timesheets.ts      timesheets, single timesheet, timeclock entries
```