peopleforce-mcp
This server is a read-only MCP connector that lets AI assistants query a PeopleForce HRIS/ATS with 27 tools.
Browse employees, filter by employment status, fetch full profiles, and look up employees by email.
View employee position history, documents, and assigned assets.
Check time-off: leave requests, leave types, and company holidays.
Explore recruitment data: vacancies, candidates, pipelines, and sources.
Access reference data: departments, positions, locations, divisions, teams, job levels, job profiles, legal entities, employment types, genders, skills, competencies, assets, and tasks.
Use the raw
api_requestescape hatch to GET any PeopleForce v3 endpoint not covered by dedicated tools.
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., "@peopleforce-mcp Who is on vacation next week in the Engineering team?"
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.
A Model Context Protocol (MCP) server that connects Claude, Cursor, Claude Desktop, and any MCP-compatible LLM client to the PeopleForce HRIS / ATS.
27 read-only tools cover the PeopleForce v3 REST API — employees, time-off, recruitment, and all reference data — so your AI assistant can answer HR questions grounded in live company data without bouncing you back to the web app.
Built and maintained by Empat — a Ukrainian custom software development company. We ship this connector as open source to make AI-assisted HR automation a commodity for every PeopleForce customer.
Why this exists
PeopleForce is one of the fastest-growing HRIS platforms in Eastern Europe, but as of 2026 it has no official MCP connector. That means Claude, Cursor, and other LLM agents can't answer questions like:
"Who is on vacation next week in the Back-end department?"
"How many people are currently on probation?"
"List all open Senior iOS vacancies we haven't filled for 30+ days."
"What leave balance does
jane.doe@example.comhave left this quarter?"
peopleforce-mcp fixes that. It is a minimal, read-only, fetch-based TypeScript server that lives on GitHub and plugs into any MCP client in a couple of commands.
Related MCP server: Tipsoi MCP
Features
✅ 27 tools across employees, time-off, recruitment, tasks, assets, and reference data.
✅ Read-only by design — the 0.x line never mutates your PeopleForce data.
✅ Clone & run — no registry accounts required, deploy from GitHub in under a minute.
✅ Actionable errors — 401 tells you to check your key, 404 tells you the endpoint isn't on v3.
✅ Built-in pagination plus a
find_employee_by_emailworkflow tool that paginates for you.✅ Escape hatch —
api_requestlets your agent hit any v3 GET endpoint not yet modelled.✅ Node.js 18 / 20 / 22 — covered by CI.
✅ Typed end-to-end, smoke-tested over stdio.
Quick start
1 — Create a PeopleForce API key
PeopleForce → Settings → Open API keys → Generate.
Pick the Company API key (full read access to employee data). Optionally restrict it to your IP range on the PeopleForce allow-list.
2 — Clone and build once
Requires Node.js 18 or newer and git.
git clone https://github.com/EmpatDevelopment/peopleforce-mcp.git ~/peopleforce-mcp
cd ~/peopleforce-mcp
npm install
npm run buildThat produces ~/peopleforce-mcp/dist/index.js, which is the only file your MCP client needs to launch.
3 — Register with your MCP client
Claude Code
claude mcp add peopleforce --scope user \
--env PEOPLEFORCE_API_KEY=your_key_here \
-- node "$HOME/peopleforce-mcp/dist/index.js"Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"peopleforce": {
"command": "node",
"args": ["/absolute/path/to/peopleforce-mcp/dist/index.js"],
"env": { "PEOPLEFORCE_API_KEY": "your_key_here" }
}
}
}Cursor — paste the same JSON into ~/.cursor/mcp.json under mcpServers.
Detailed per-client guides with screenshots-friendly JSON snippets are in examples/.
Configuration
All configuration is passed via environment variables.
Variable | Default | Purpose |
| required | Your PeopleForce Company API key. |
|
| Override if PeopleForce hosts you on a non-default endpoint. |
|
| Per-request timeout. Slow PeopleForce responses are aborted and retried. |
|
| Max automatic retries for |
|
| Base for exponential backoff with full jitter. Retry-After headers are honoured. |
4 — Keeping it up to date
cd ~/peopleforce-mcp && git pull && npm install && npm run buildRestart your MCP client after each update.
5 — Ask something
"How many people are on probation right now, and which departments are they in?"
The model will call peopleforce_list_employees with status=probation, paginate through the results, and summarise.
Tool reference
Every tool is prefixed with peopleforce_ and is read-only. All list tools accept page (≥ 1) and per_page (≤ 100).
Employees
Tool | Purpose |
| Paginated roster; filter by |
| Full profile by numeric |
| Looks up an employee by work or personal email; paginates internally. |
| Position / role history for one employee. |
| Documents attached to one employee. |
| Assets assigned to one employee. |
Time-off & calendar
Tool | Purpose |
| Filter by |
| Vacation, sick, optional holiday, etc. |
| Official company holidays. |
Recruitment / ATS
Tool | Purpose |
| Open & closed jobs. |
| Candidates in the pipeline. |
| Pipelines and their stages. |
| Where candidates came from. |
Reference data
list_departments, list_positions, list_locations, list_divisions, list_teams, list_job_levels, list_job_profiles, list_legal_entities, list_employment_types, list_genders, list_skills, list_competencies, list_assets, list_tasks.
Escape hatch
api_request — raw GET against any /api/public/v3/<path> with an optional query object. Use it when the endpoint you need isn't modelled above, and consider opening a PR to promote it to a first-class tool.
Troubleshooting
Could not attach to MCP server peopleforce / Server disconnected
Check the client log for the underlying stderr — the toast never carries it.
Log | Client |
| Claude Desktop (macOS) |
| Claude Code |
Two failure modes account for almost all of these:
Error: Cannot find module '.../dist/index.js'— the absolute path in your client config no longer exists. Every client config stores its own copy of that path, so moving or re-cloning the repo breaks each one independently. Fix theargsentry, then fully restart the client (config is read at startup).ERROR: PEOPLEFORCE_API_KEY env var not set— the key is missing from theenvblock of that config. The server refuses to start without it rather than failing later on every call.
If the path and key are both correct, run the server by hand — a clean handshake rules out the server itself:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
| PEOPLEFORCE_API_KEY=your_key_here node dist/index.jsSecurity
This server requires a PeopleForce Company API key, which is effectively read access to your entire employee database. Read SECURITY.md for full guidance — tl;dr:
Store it only in
PEOPLEFORCE_API_KEY(env var or your MCP client's encrypted config).Never commit it; never paste it into chat, Slack, or Notion.
Rotate immediately if leaked (PeopleForce → Settings → Open API keys → Revoke + Generate).
Restrict to allow-listed IPs where your MCP client runs.
Development
git clone https://github.com/EmpatDevelopment/peopleforce-mcp.git
cd peopleforce-mcp
npm install
npm test # unit + stdio smoke tests (no PeopleForce account required)
npm run build
PEOPLEFORCE_API_KEY=xxx node dist/index.js # run locallyFull contribution guide: CONTRIBUTING.md.
FAQ
Does it write to PeopleForce? No. 0.x is read-only by design. Mutating tools would be opt-in via a future feature flag.
Does it store my data anywhere? No. The server is a stateless stdio proxy between your MCP client and the PeopleForce API. Requests never leave the process.
Is it rate-limited? PeopleForce rate-limits the API itself. The server surfaces any 429 responses as actionable errors; it does not retry automatically.
Which PeopleForce plans are supported? Any plan that exposes the v3 API. The Career key has a narrower scope (vacancies only) and will 404 on most tools — use a Company key.
Can I self-host it? Yes — it's pure Node.js 18+. Run node dist/index.js inside any container with the env var set.
About Empat
Empat is a product-focused custom software development company based in Lviv, Ukraine. Since 2013 we have delivered 300+ projects across 23 markets — including fintech software development, AI software development, SaaS development, and custom mobile app development for Y Combinator alumni, Fortune 500 companies, and 19 Forbes 30 Under 30 founders.
Ways we work with clients:
Full product development — Discovery, PoC, MVP, launch, growth.
CTO as a service for early-stage founders.
Dedicated developer hiring and IT staff augmentation (iOS, Android, Flutter, React Native, Node.js, Python, .NET, QA, DevOps, Design).
Product validation and consulting.
Industries we serve: healthcare (remote monitoring, tele-consultations), fintech (payments, banking, commissions), social networks, education, entertainment & gaming, e-commerce.
5.0 on Clutch · Top 100 Fastest Growth 2026 · 300+ delivered products · $380M raised by clients in 2023.
👉 empat.tech — tell us what you're building.
License
MIT © 2026 Empat.
Available Tools
28 toolspeopleforce_api_requestARead-only
Escape hatch: perform a raw GET against any PeopleForce v3 API path (relative to /api/public/v3). Use when no dedicated tool covers the endpoint. Example path: 'employees/12345' or 'leave_requests?state=approved'.
Inputs: path (required), query.
peopleforce_find_employee_by_emailARead-only
Find a single employee by work or personal email. Paginates internally until a match is found. Returns the full employee object or null.
Inputs: email (required).
peopleforce_get_employeeARead-only
Get a single employee by PeopleForce id. Returns full profile including position, department, manager, custom fields.
Inputs: id (required).
peopleforce_list_assetsBRead-only
List all assets/equipment in the company.
Inputs: page, per_page.
peopleforce_list_competenciesARead-only
List competencies used in performance reviews.
Inputs: page, per_page.
peopleforce_list_departmentsARead-only
List all departments with manager and parent info.
Inputs: page, per_page.
peopleforce_list_divisionsBRead-only
List organizational divisions.
Inputs: page, per_page.
peopleforce_list_employee_assetsARead-only
List assets/equipment assigned to a specific employee.
Inputs: employee_id (required), page, per_page.
peopleforce_list_employee_documentsBRead-only
List documents attached to a specific employee's profile.
Inputs: employee_id (required), page, per_page.
peopleforce_list_employee_positionsARead-only
List position history for a specific employee (promotions, role changes, compensation).
Inputs: employee_id (required), page, per_page.
peopleforce_list_employeesARead-only
List employees with pagination. Only the status filter is applied server-side; filter other attributes client-side or use peopleforce_find_employee_by_email.
Inputs: page, status, per_page.
peopleforce_list_employment_typesARead-only
List employment types (Full-time, Part-time, Contractor, etc).
Inputs: page, per_page.
peopleforce_list_gendersARead-only
List gender reference values used in profiles.
Inputs: page, per_page.
peopleforce_list_holidaysBRead-only
List official company holidays.
Inputs: page, per_page.
peopleforce_list_job_levelsARead-only
List job levels (Junior/Middle/Senior/etc).
Inputs: page, per_page.
peopleforce_list_job_profilesBRead-only
List job profiles (role descriptions).
Inputs: page, per_page.
peopleforce_list_leave_requestsARead-only
List leave/time-off requests. Useful for 'who's on vacation', balance queries, approvals. Supports employee_id and state filters.
Inputs: page, state, per_page, employee_id, +1 more.
peopleforce_list_leave_typesARead-only
List leave/time-off types (Vacation, Sick, Optional holiday, etc) with units and colors.
Inputs: page, per_page.
peopleforce_list_legal_entitiesARead-only
List legal entities employees are contracted under.
Inputs: page, per_page.
peopleforce_list_locationsARead-only
List office/remote locations.
Inputs: page, per_page.
peopleforce_list_positionsARead-only
List all position titles used in the company.
Inputs: page, per_page.
peopleforce_list_recruitment_candidatesARead-only
List candidates in the ATS pipeline.
Inputs: page, per_page.
peopleforce_list_recruitment_pipelinesARead-only
List recruitment pipelines with their stages.
Inputs: page, per_page.
peopleforce_list_recruitment_sourcesARead-only
List recruitment sources (where candidates came from).
Inputs: page, per_page.
peopleforce_list_recruitment_vacanciesARead-only
List open and closed vacancies in the ATS.
Inputs: page, per_page.
peopleforce_list_skillsBRead-only
List skills tracked in the skills matrix.
Inputs: page, per_page.
peopleforce_list_tasksARead-only
List tasks assigned across the organization (onboarding, offboarding, HR actions).
Inputs: page, per_page.
peopleforce_list_teamsBRead-only
List teams (cross-functional groupings).
Inputs: page, per_page.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Each tool targets a distinct entity or action. List tools all differ by the entity they list (e.g., assets, competencies, departments), and lookup tools (get, find) are clearly separated from lists. No overlap in purpose.
All tools follow a consistent pattern: 'peopleforce_' + verb (list, get, find) + '_' + entity. The verb clearly indicates the action, and all names use lowercase with underscores, ensuring predictability.
With 28 tools, the server exceeds the typical well-scoped range of 3-15 and falls into the 'too many' category (25+). While the HR domain has many entities, the sheer number of list tools feels excessive, especially since many are simple reference data lookups.
The tool set is heavily skewed towards read-only list operations. Missing dedicated create/update/delete tools for core entities like employees and leave requests, forcing agents to rely on the raw API escape hatch. This leaves significant gaps in typical HR workflows.
Maintenance
Related MCP Connectors
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
Connect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Related MCP Servers
- 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.1914 npm4MIT
- FlicenseAqualityDmaintenanceRead-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.153-
- FlicenseNot gradedqualityCmaintenanceExposes SAP SuccessFactors HR data as MCP tools for AI agents, enabling natural language queries about employees, jobs, performance, and organizational structure.-
- FlicenseNot gradedqualityDmaintenanceExposes read-only PostgreSQL-backed HR data through seven structured tools, including employee directory lookups, late arrival and absence reporting, and delay summarization, all validated with Zod and returning queryable structured content.1-