HR Partner MCP Server

A Model Context Protocol (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 company using the HR Partner public API.

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

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

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.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

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:

{
  "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. 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

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

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
    timesheets.ts      timesheets, single timesheet, timeclock entries