@calybur/mcp

Official MCP server for Calybur — connect external MCP-compatible agents to your Malaysian payroll and HR data via the Partner API.

Most Calybur customers use AI Workspace inside the product for day-to-day questions. This package is for integrators who want Claude Desktop, custom agents, automation runners, or any MCP client to query Calybur with an API key.

Requirements

• Node.js 20+
• Calybur Starter plan or above
• API key with read scope — create at Settings → API Keys in Calybur
• Optional MCP setup copy at Settings → Integrations

Setup in Calybur

1. Create a Partner API key (ezg_live_*) with read scope.
2. Open Settings → Integrations and copy the MCP config snippet, or use the example below.
3. Paste the config into your MCP client (stdio transport).

Connect any MCP client

{
  "mcpServers": {
    "calybur": {
      "command": "npx",
      "args": ["-y", "@calybur/mcp@latest"],
      "env": {
        "CALYBUR_API_KEY": "ezg_live_your_key_here"
      }
    }
  }
}

Restart your MCP client and enable the Calybur tools. Cursor, Claude Desktop, and other stdio MCP hosts use the same shape; only the config file location differs.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CALYBUR_API_KEY | Yes | Partner API key (ezg_live_*) | | CALYBUR_PLAN | No | starter (default), professional, or enterprise | | CALYBUR_API_BASE_URL | No | Defaults to https://api.calybur.com | | CALYBUR_SUPABASE_PUBLISHABLE_KEY | No | Only if bypassing the gateway with a direct Supabase URL |

Tools (MVP — read-only)

| Tool | Purpose | |------|---------| | calybur_workforce | Query employees, departments, positions, and work locations from Calybur. | | calybur_leave | Query leave balances, requests, policies, and public holidays. | | calybur_payroll | Query payroll periods, run status, and payslips. | | calybur_attendance | Query attendance events and summaries. | | calybur_commission | Query commission rules and calculation results. | | calybur_reports | Fetch payroll summary or statutory export metadata for a period. | | calybur_status | Check API key validity and remaining MCP client rate budget. | | calybur_docs | Search bundled Calybur API and Malaysia statutory documentation. |

Actions by tool

• calybur_workforce: list_employees, get_employee, list_departments, list_positions, list_work_locations
• calybur_leave: list_balances, list_requests, list_policies, list_holidays
• calybur_payroll: list_periods, get_run, list_payslips
• calybur_attendance: list_events, list_summaries
• calybur_commission: list_rules, list_calculations
• calybur_reports: payroll_summary, statutory_metadata

calybur_status and calybur_docs have dedicated input shapes (no action enum).

Example prompts

• "Use calybur_status to verify my API connection"
• "List active employees with calybur_workforce"
• "Show March payroll periods with calybur_payroll"

Development

cd packages/calybur-mcp
npm install
npm test
npm run build
CALYBUR_API_KEY=ezg_live_... npm run dev

Rate limits

| Plan | API limit | MCP client budget (90%) | |------|-----------|-------------------------| | Starter | 100/min | 90/min | | Professional | 500/min | 450/min | | Enterprise | 2000/min | 1800/min |

License

MIT

Publishing

See PUBLISHING.md. Published package: @calybur/mcp on npm.