Skip to main content
Glama
peopleforce-mcp

peopleforce-mcp

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.

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

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

~/Library/Logs/Claude/mcp-server-peopleforce.log

Claude Desktop (macOS)

~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-peopleforce/*.jsonl

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 the args entry, then fully restart the client (config is read at startup).

  • ERROR: PEOPLEFORCE_API_KEY env var not set — the key is missing from the env block 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.js

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.

Available Tools

28 tools
peopleforce_api_requestA
Read-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_emailA
Read-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_employeeA
Read-only

Get a single employee by PeopleForce id. Returns full profile including position, department, manager, custom fields.

Inputs: id (required).

peopleforce_list_assetsB
Read-only

List all assets/equipment in the company.

Inputs: page, per_page.

peopleforce_list_competenciesA
Read-only

List competencies used in performance reviews.

Inputs: page, per_page.

peopleforce_list_departmentsA
Read-only

List all departments with manager and parent info.

Inputs: page, per_page.

peopleforce_list_divisionsB
Read-only

List organizational divisions.

Inputs: page, per_page.

peopleforce_list_employee_assetsA
Read-only

List assets/equipment assigned to a specific employee.

Inputs: employee_id (required), page, per_page.

peopleforce_list_employee_documentsB
Read-only

List documents attached to a specific employee's profile.

Inputs: employee_id (required), page, per_page.

peopleforce_list_employee_positionsA
Read-only

List position history for a specific employee (promotions, role changes, compensation).

Inputs: employee_id (required), page, per_page.

peopleforce_list_employeesA
Read-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_typesA
Read-only

List employment types (Full-time, Part-time, Contractor, etc).

Inputs: page, per_page.

peopleforce_list_gendersA
Read-only

List gender reference values used in profiles.

Inputs: page, per_page.

peopleforce_list_holidaysB
Read-only

List official company holidays.

Inputs: page, per_page.

peopleforce_list_job_levelsA
Read-only

List job levels (Junior/Middle/Senior/etc).

Inputs: page, per_page.

peopleforce_list_job_profilesB
Read-only

List job profiles (role descriptions).

Inputs: page, per_page.

peopleforce_list_leave_requestsA
Read-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_typesA
Read-only

List leave/time-off types (Vacation, Sick, Optional holiday, etc) with units and colors.

Inputs: page, per_page.

peopleforce_list_locationsA
Read-only

List office/remote locations.

Inputs: page, per_page.

peopleforce_list_positionsA
Read-only

List all position titles used in the company.

Inputs: page, per_page.

peopleforce_list_recruitment_candidatesA
Read-only

List candidates in the ATS pipeline.

Inputs: page, per_page.

peopleforce_list_recruitment_pipelinesA
Read-only

List recruitment pipelines with their stages.

Inputs: page, per_page.

peopleforce_list_recruitment_sourcesA
Read-only

List recruitment sources (where candidates came from).

Inputs: page, per_page.

peopleforce_list_recruitment_vacanciesA
Read-only

List open and closed vacancies in the ATS.

Inputs: page, per_page.

peopleforce_list_skillsB
Read-only

List skills tracked in the skills matrix.

Inputs: page, per_page.

peopleforce_list_tasksA
Read-only

List tasks assigned across the organization (onboarding, offboarding, HR actions).

Inputs: page, per_page.

peopleforce_list_teamsB
Read-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

    B3.4/5.0

    Scored across 28 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness2/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
      14 npm
      4
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.
      15
      3
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Exposes SAP SuccessFactors HR data as MCP tools for AI agents, enabling natural language queries about employees, jobs, performance, and organizational structure.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes 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
      -