peopleforce-mcp

<p align="center"> <a href="https://www.empat.tech"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./assets/empat-logo-white.svg"> <img src="./assets/empat-logo-black.svg" alt="Empat" width="180"> </picture> </a> </p>

<h1 align="center">peopleforce-mcp</h1>

<p align="center"> <a href="https://github.com/EmpatDevelopment/peopleforce-mcp/actions/workflows/ci.yml"><img src="https://github.com/EmpatDevelopment/peopleforce-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="./LICENSE"><img src="https://img.shields.io/github/license/EmpatDevelopment/peopleforce-mcp.svg" alt="MIT License"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node 18+"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-blue.svg" alt="MCP compatible"></a> <a href="https://www.empat.tech"><img src="https://img.shields.io/badge/built%20by-Empat-000000.svg" alt="Built by Empat"></a> </p>

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.com have 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.

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_email workflow tool that paginates for you.
• ✅ Escape hatch — api_request lets 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 build

That 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
PEOPLEFORCE_API_KEY	required	Your PeopleForce Company API key.
PEOPLEFORCE_BASE_URL	https://app.peopleforce.io/api/public/v3	Override if PeopleForce hosts you on a non-default endpoint.
PEOPLEFORCE_TIMEOUT_MS	15000	Per-request timeout. Slow PeopleForce responses are aborted and retried.
PEOPLEFORCE_MAX_RETRIES	3	Max automatic retries for 429 / 5xx / network timeouts. Set to 0 to disable.
PEOPLEFORCE_RETRY_BASE_MS	500	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 build

Restart 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
list_employees	Paginated roster; filter by status (employed / probation / dismissed / …).
get_employee	Full profile by numeric id.
find_employee_by_email	Looks up an employee by work or personal email; paginates internally.
list_employee_positions	Position / role history for one employee.
list_employee_documents	Documents attached to one employee.
list_employee_assets	Assets assigned to one employee.

Time-off & calendar

Tool	Purpose
list_leave_requests	Filter by employee_id, state (pending / approved / rejected / cancelled), leave_type_id.
list_leave_types	Vacation, sick, optional holiday, etc.
list_holidays	Official company holidays.

Recruitment / ATS

Tool	Purpose
list_recruitment_vacancies	Open & closed jobs.
list_recruitment_candidates	Candidates in the pipeline.
list_recruitment_pipelines	Pipelines and their stages.
list_recruitment_sources	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.

Security

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 locally

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