Skip to main content
Glama
HR Partner MCP Server

HR Partner MCP Server

Official
by HR-Partner

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.

Related MCP server: Rippling MCP Server

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. 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):

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

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

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

Available Tools

49 tools
add_timeclock_entryAdd Timeclock EntryA

Add a timesheet/timeclock entry for an employee. Times are the employee's LOCAL time in 'yyyy-mm-dd hh:mm' format. Entries can only be added to OPEN timesheet sequences, and the timeclock module must be enabled for the company and the employee's timesheet template. Identify the employee with either employee_code or employee_email.

Inputs: end_time (required), start_time (required), notes, duration, +5 more.

delete_reminderDelete ReminderA

Permanently delete a reminder by its unique ID. This cannot be undone.

Inputs: id (required).

get_applicantGet ApplicantA

Get a single applicant by unique ID or email address, including their job applications with stage, scores and flags.

Inputs: applicant_id (required).

get_applicationGet ApplicationA

Get a single job application by its numeric ID, including applicant details, stage, job listing, custom form answers, scorecards, attachments, interviews and comments. Use list_applications to find application IDs.

Inputs: application_id (required).

get_application_stage_trackingGet Application Stage TrackingA

Get the history of job applications moving between recruitment pipeline stages. Maximum 500 records per response, so use filters to stay below the limit.

Inputs: job, to_stage, applicant, from_stage, +3 more.

get_companyGet Company InfoA

Get basic company information from HR Partner: company name, subscription status and expiry, employee counts, and timezone. Useful for validating the API key is connected to the correct company.

Inputs: custom_fields, active_modules.

get_employeeGet Employee DetailsA

Get full details for a single employee by Employee Code, including contact details, addresses, tags, and any custom fields configured for the company. Use list_employees first to find employee codes.

Inputs: code (required).

get_jobGet Job ListingA

Get a single job listing by its unique job ID/slug (e.g. 'forklift-driver-oz0H'), including selection panel, custom application form definition, scorecard, pipeline stages and full text/web content. Use list_jobs to find job IDs.

Inputs: job_id (required).

get_leave_requestGet Leave RequestA

Get a single leave request by ID, including approver action history, approval conditions, extended employee details and file attachments. Use list_leave_requests to find IDs.

Inputs: id (required).

get_library_categoriesGet Library CategoriesA

Get the document library category list. The 'detailed' view also includes parent and child category relationships.

Inputs: detail, max_records.

get_library_documentsGet Library DocumentsA

Get documents from the HR Partner document library (policies, handbooks etc.), optionally limited to one category. Returns description, download URL, size and timestamps.

Inputs: max_records, category_slug.

get_lookupGet Lookup ValuesA

Get the valid values for an HR Partner lookup list (departments, locations, positions, absence reasons, review types, tags etc.). Use this to discover valid filter values for the other tools. Lookups are read-only via the API.

Inputs: lookup_name (required), max_records.

get_reminderGet ReminderA

Get a single reminder by its unique ID. Use list_reminders to find reminder IDs.

Inputs: id (required).

get_timesheetGet Single TimesheetA

Get a single employee's timesheet for one sequence (period). Returns the same structure as list_timesheets for one employee/sequence combination.

Inputs: employee (required), sequence (required).

list_absencesList Employee AbsencesB

Get employee absence records (leave taken, or TOIL/Flexi leave added). Includes absence reason, status, dates, duration, physician/certificate details and attachments.

Inputs: type, group, comments, employee, +12 more.

list_addressesList Employee AddressesA

Get a flat list of employee addresses across employees. Individual employee addresses are also included in the get_employee response.

Inputs: search, max_records, address_type, location_search.

list_anniversariesList Employee AnniversariesA

Get upcoming employee work anniversaries (active, non-terminated employees only) with years worked. Filter by month range and optionally forecast service length for a future year.

Inputs: group, location, position, end_month, +5 more.

list_applicantsList ApplicantsA

Get recruitment applicants (candidates). Search matches first name, last name or email (including email domain).

Inputs: search, max_records.

list_applicationsList Job ApplicationsA

Get applications for a specific job listing (the API cannot list applications across all jobs at once). Includes applicant details, stage, source, flags and custom form answers.

Inputs: job_id (required), stage, source, is_read, +6 more.

list_assetsList Employee AssetsA

Get company assets allocated to employees (e.g. phones, laptops), including identifiers, serial numbers, allocation/return dates and attachments.

Inputs: employee, asset_type, department, in_date_to, +7 more.

list_attachmentsList Employee AttachmentsA

Get file attachments stored against employee records, with description (file name), download URL, size, and the module they belong to.

Inputs: module, employee, department, description, +3 more.

list_benefitsList Employee BenefitsA

Get employee benefit records (health cover, allowances etc.) including type, status, provider, value and dates.

Inputs: comments, employee, department, description, +10 more.

list_birthdaysList Employee BirthdaysA

Get upcoming employee birthdays (active, non-terminated employees only) with calculated age. Filter by month range and optionally forecast ages for a future year.

Inputs: location, position, end_month, department, +4 more.

list_checklistsList ChecklistsA

Get employee checklists (onboarding/offboarding etc.) with status, progress percentage, assigned/completed dates.

Inputs: employee, max_records, show_details, assigned_date_to, +5 more.

list_contactsList Employee ContactsA

Get a contact-centric list of employee contact records across multiple employees. Individual employee contacts are also included in the get_employee response.

Inputs: search, is_public, is_primary, max_records, +2 more.

list_dependentsList Employee DependentsA

Get employee dependent / next-of-kin records including type, name, contact details and date of birth.

Inputs: name, comments, employee, department, +5 more.

list_educationList Employee EducationB

Get employee education history records including institution, qualification, type, status and commence/completion dates.

Inputs: comments, employee, department, institution, +8 more.

list_employeesList EmployeesA

Get a list of employees in HR Partner with optional filters. Returns summary details per employee (code, name, department, location, position, status flags, dates). Use get_employee with the employee 'code' for full details including contacts, addresses and custom fields.

Inputs: tag, group, search, location, +17 more.

list_expensesList Expense ClaimsA

Get employee expense claims. The report_type controls the shape: 'detailed' returns claim headers plus expense lines and attachments, 'summary' returns claim headers only, 'transaction' returns expense lines only.

Inputs: report_type (required), status, is_paid, project, +11 more.

list_goalsList GoalsA

Get company and employee goals with scope, type, target/current values, completion and due dates.

Inputs: comments, employee, goal_type, goal_scope, +10 more.

list_grievancesList Employee GrievancesA

Get employee grievance / complaint / harassment records including type, status, description, actioned-by and reported dates.

Inputs: employee, department, actioned_by, description, +5 more.

list_interviewsList Employee InterviewsA

Get employee interview / meeting records including type, interviewer, description and dates.

Inputs: employee, department, description, interviewer, +4 more.

list_jobsList Job ListingsA

Get recruitment job listings with title, department, location, position, publish dates and flags. Use get_job with the job id/slug for full detail including application form, scorecard and pipeline stages.

Inputs: search, location, position, is_active, +12 more.

list_leave_balancesList Leave BalancesA

Get employee leave balances per leave policy: entitlement, current balance, carryover, units and accrual details. Warning: balances are slow to compute, so always filter to the smallest dataset needed (e.g. a single employee or policy).

Inputs: employee, location, position, is_active, +5 more.

list_leave_requestsList Leave RequestsA

Get employee leave (time off) requests with status, absence reason (leave policy), dates, duration and description. Use get_leave_request for full approval detail on one request.

Inputs: notes, reason, status, employee, +10 more.

list_notesList Employee NotesB

Get employee notes including note text, hashtags, created/updated dates and optional change-event history.

Inputs: note, tags, employee, department, +6 more.

list_performancesList Performance ReviewsA

Get performance review cycles with status, template, assigned/review/completed dates. Optionally include individual form statuses (employee/manager/peer/user) and the full questions and answers (significantly increases response time, so combine with other filters).

Inputs: employee, location, position, form_data, +11 more.

list_positionsList Employee Position HistoryB

Get employee position (job) history records including position name, remuneration, pay level and commence/completion dates.

Inputs: comments, employee, paylevel, position, +8 more.

list_projectsList Projects & ActivitiesA

Get project/activity costing entries (from timesheets and expenses) with employee, project, activity, currency, hours/cost and transaction dates.

Inputs: project, activity, currency, employee, +6 more.

list_remindersList RemindersB

Get admin reminders with description, module, remind date, notification flags and the responsible user/employee.

Inputs: user, active, module, employee, +4 more.

list_renewablesList Employee RenewablesB

Get employee renewable document records (licences, certifications, visas etc.) including type, description, issue date and renewal due date.

Inputs: comments, employee, department, description, +6 more.

list_reviewsList Employee ReviewsA

Get employee review records (probation reviews, performance check-ins etc.) including type, status, reviewer, score and review dates. For full performance review forms see list_performances.

Inputs: comments, employee, reviewer, score_to, +8 more.

list_skillsList Employee SkillsB

Get employee skill records including skill name, rating and comments.

Inputs: comments, employee, department, skill_name, +4 more.

list_timesheetsList TimesheetsA

Get timesheet data grouped by timesheet template, sequence (period), employee and individual time entries. Warning: can return a LOT of data; always use date ranges or employee filters to avoid timeouts.

Inputs: group, status, project, activity, +12 more.

list_trainingList Employee TrainingB

Get employee training course records including type, status, course name, institution, cost, reimbursement and commence/completion dates.

Inputs: cost_to, comments, employee, cost_from, +12 more.

save_applicantAdd or Update ApplicantA

Create a new applicant or update an existing one (upsert by email). Can also link the applicant to one or more job listings and move them to a pipeline stage (the stage name must already exist).

Inputs: email (required), last_name, first_names, job_applications.

save_applicationAdd or Update Job ApplicationA

Create a new job application or update an existing one. Also upserts the applicant by email. An invalid stage name results in the company default stage (usually 'Applied'). Custom form answers are keyed by the form field names from the job listing's custom form (see get_job).

Inputs: job_id (required), applicant_email (required), stage_name, application_id, +3 more.

save_employeeAdd or Update EmployeeA

Create a new employee or update an existing one in HR Partner (upsert by Employee Code). Only supplied fields are modified. Custom fields go in custom_data (only the keys you want to change are needed). New values for department/location/position/employment_status are added to the lookup lists automatically. Note: tags, contacts and addresses can be added/updated but NOT deleted via the API.

Inputs: code (required), tags, location, position, +20 more.

update_reminderUpdate ReminderA

Update a reminder's description and flags. Note: the employee, admin user and reminder date CANNOT be changed via the API, only the description and the notification/active flags.

Inputs: id (required), active, description, notification_sent, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 49 tools

    Disambiguation4/5

    Most tools are clearly distinct, each targeting a specific entity type (e.g., absences, benefits, skills). Some potential overlap exists (list_contacts/list_addresses vs get_employee; list_absences vs list_leave_requests; list_reviews vs list_performances), but descriptions clarify the differences. Overall, an agent can usually tell which tool to use.

    Naming Consistency5/5

    The naming convention is highly consistent: list_* for collections, get_* for individual items, save_* for upserts, and specific verbs for other actions (delete_reminder, update_reminder, add_timeclock_entry). Minor deviations like add_timeclock_entry instead of save_timeclock_entry do not break the pattern.

    Tool Count2/5

    With 49 tools, this is a large tool surface. Even for a broad HR platform, many tools are read-only list_* endpoints for different record types, which can overwhelm an agent and make tool selection harder. The count significantly exceeds the typical well-scoped range.

    Completeness4/5

    The tool set covers a wide range of HR domains: employee lifecycle, recruitment, leave, timesheets, reminders, and document library. Core entities support create/update via save_* tools, and reminders have full CRUD. Some areas are read-only (e.g., benefits, skills), but this likely reflects API limitations. Overall, coverage is comprehensive, with minor gaps like no delete for employees or applications.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with BambooHR's API through natural language queries. Provides access to employee data, time off management, company files, and HR operations with comprehensive tools for workforce management.
      108 npm
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Connects AI agents to the Rippling HR/IT/Finance platform to query employees, manage leave requests, and view organizational structures. It provides eighteen tools for accessing company data, employee details, and administrative activities through the Rippling API.
      19
      22 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 50+ tools for interacting with Rippling's HR platform, including employee management, payroll, time tracking, benefits, recruiting, learning, devices, groups, and custom objects, all through natural language.
      MIT