employes-mcp

MCP server for the Employes payroll API (public API v4), generated from the OpenAPI spec. Exposes all 27 endpoints as tools: companies, employees, employments (contracts, salaries, hours, tax details, termination), payruns, payslips, annual statements, wage components and time-off requests.

Setup

npm install
npm run build

Generate an API token in the Employes web app (click your name in the bottom-left corner → generate token; valid for one year).

Configuration

Environment variable	Required	Description
EMPLOYES_API_TOKEN	yes	Bearer token from the Employes web app
EMPLOYES_COMPANY_ID	no	Default company id; when set, company_id can be omitted on every tool call
EMPLOYES_ENV	no	production (default) or sandbox (uses the /acc base path)
EMPLOYES_BASE_URL	no	Full base URL override; takes precedence over EMPLOYES_ENV

Registering with Claude Code

claude mcp add employes \
  --env EMPLOYES_API_TOKEN=your-token-here \
  --env EMPLOYES_COMPANY_ID=your-company-id \
  -- node /home/deprekated/Projects/home/employes-mcp/dist/index.js

Or in any MCP client's JSON config:

{
  "mcpServers": {
    "employes": {
      "command": "node",
      "args": ["/home/deprekated/Projects/home/employes-mcp/dist/index.js"],
      "env": {
        "EMPLOYES_API_TOKEN": "your-token-here",
        "EMPLOYES_COMPANY_ID": "your-company-id"
      }
    }
  }
}

Notes

• download_payslip and download_annual_statement save the PDF to disk (default: the current working directory) and return the file path, since MCP text responses can't carry binaries usefully.
• sync_employees is the way to list employees — the API has no plain "list employees" endpoint; sync returns all employees including contract, salary and tax details.
• Write tools (create_*, update_*, terminate_employment, …) hit the live payroll administration. Point EMPLOYES_ENV=sandbox at the sandbox environment for testing.
• Wage-component ids for update_payrun_employee are documented at https://employes.readme.io/v4.0/docs/regulations; get_regulations lists what's available for your company.