HR Partner MCP Server
OfficialThis server provides an MCP interface to read and write HR Partner data, enabling AI assistants to manage employees, leave, expenses, recruitment, and more.
Employee Management: List employees with rich filters; get full details (contacts, addresses, tags, custom fields); create/update employees (upsert by code), including custom fields, tags, contacts, and addresses.
Employee Sub-Records: Access 14 sub-modules with filtering: absences, assets, attachments, benefits, dependents, education, grievances, interviews, notes, position history (including remuneration), renewables (licenses/certifications/visas), reviews, skills with ratings, and training with cost/reimbursement.
Organisation & Lookup: List company goals, checklists, upcoming birthdays and anniversaries, document library and categories, and get valid lookup values for 30+ lists (departments, locations, tags, etc.).
Leave, Time & Money: List and retrieve leave requests with approval history; view leave balances (entitlements, carryover); list timesheets and individual timesheets; add timeclock entries; list expense claims (detailed/summary/transaction); list projects and activities.
Performance & Reminders: List performance reviews (with optional form answers); list, get, update, and delete reminders.
Recruitment & Applicant Tracking: Manage full recruitment lifecycle: list/get job listings, applicants, applications, and stage tracking; create/update applicants and applications (upsert).
Security & Read-Only Mode: Support
HR_PARTNER_READ_ONLYto disable write tools; API key kept local, base URL validated to HTTPS/localhost, no cleartext data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HR Partner MCP Server Who is on leave next week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
An active HR Partner subscription (trial or paid).
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.
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 buildThis 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 |
| Yes | Your HR Partner API key |
| No | API base URL, defaults to |
| No | Set to |
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.jsChatGPT and other MCP clients
Any client that supports MCP stdio servers can use this server with the same building blocks:
Command:
nodeArgs:
["/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 |
| Company name, subscription, employee counts, timezone; good connectivity test |
| Employees with filters (department, location, status, dates, tags, reports-to, ...) |
| Full employee record by code: contacts, addresses, tags, custom fields |
| Create or update an employee (upsert by code), incl. custom fields, tags, contacts, addresses |
| Contact records across employees |
| 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=1to 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_URLis validated before any request is sent: onlyhttps://URLs (orhttp://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 stdioProject 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 entriesAvailable Tools
49 toolsadd_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
Scored across 49 tools
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.
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.
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.
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
Connect your AI assistant to your Peak HR portal: HR operations, people, documents and drafts.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
PeopleHR MCP server for ChatGPT, Claude and any AI agent: list holiday requests, approve holiday request, decline holiday request, list employees, get employee planner, create task and run saved query in your own PeopleHR account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to PeopleHR yourself; Cotlet does not store your password and you need no PeopleHR API key. About the official PeopleHR API: PeopleHR has a REST API, the Access PeopleHR Integration API v4.0, but no official MCP server (checked 22 Oct 2026). The API covers 31 resources and 150 actions, mostly employee records, holiday and absence data, and every call needs an API key that an HR admin creates in Settings. Setup and FAQ: https://cotlet.dev/integrations/peoplehr-api-mcp-server
Read intelliHR people, jobs, leave, skills and training; create and update people records.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm1MIT
- AlicenseBqualityDmaintenanceConnects 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.1922 npm4MIT
- AlicenseBqualityDmaintenanceEnables interaction with the Officient HR API to manage people, days off, and salary slips through natural language.9MIT
- AlicenseNot gradedqualityDmaintenanceProvides 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