keka-mcp-server
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., "@keka-mcp-server List employees hired this month"
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.
keka-mcp-server
MCP server for the Keka HRM API, built for White Label IQ (WLIQ).
Exposes 14 tools covering Keka's core modules so Claude (or any MCP client) can query and act on HR data.
Tools
HRIS
Tool | Description |
| List employees with filters (status, search, probation, etc.) |
| Get full details for a single employee by ID |
| List all departments |
| List all job titles |
| List all groups/teams |
Leave Management
Tool | Description |
| List configured leave types (Annual, Sick, etc.) |
| List leave requests with date/employee filters |
| Submit a new leave request for an employee |
| Get leave balance breakdown per employee |
Attendance
Tool | Description |
| Get attendance records (clock-in/out, hours, status) |
Payroll
Tool | Description |
| List payroll groups |
| List salary pay bands |
| List employee salaries (CTC, pay group) |
Recruitment (Keka Hire)
Tool | Description |
| List job openings |
| List candidates for a specific job |
PSA
Tool | Description |
| List PSA clients |
| List PSA projects |
Related MCP server: Tipsoi MCP
Setup
1. Get Keka API credentials
In your Keka admin portal:
Go to Settings → Integrations → API
Create a new API access key
Note down:
Client ID,Client Secret,API Key
2. Install dependencies
npm install3. Build
npm run build4. Environment variables
Variable | Required | Description |
| ✅ | Your Keka tenant URL, e.g. |
| ✅ | OAuth2 Client ID from Keka admin |
| ✅ | OAuth2 Client Secret |
| ✅ | API key from Keka admin |
| Optional | Your own Keka employee ID — used as |
| Optional | Set to |
| Optional |
|
| Optional | HTTP port when |
Claude Desktop integration (stdio)
Add to your claude_desktop_config.json:
{
"mcpServers": {
"keka": {
"command": "node",
"args": ["/path/to/keka-mcp-server/dist/index.js"],
"env": {
"KEKA_BASE_URL": "https://yourcompany.keka.com",
"KEKA_CLIENT_ID": "your-client-id",
"KEKA_CLIENT_SECRET": "your-client-secret",
"KEKA_API_KEY": "your-api-key",
"KEKA_EMPLOYEE_ID": "your-employee-uuid"
}
}
}
}HR Skill Prompt (optional)
Copy the contents of keka-hr-skill.md into Claude Desktop's Custom Instructions (Settings → Custom Instructions). This teaches Claude how to handle Keka operations smoothly — resolving names to IDs, always including required fields, checking balances before applying leave, etc.
## HTTP mode (remote deployment)
```bash
TRANSPORT=http \
KEKA_BASE_URL=https://yourcompany.keka.com \
KEKA_CLIENT_ID=xxx \
KEKA_CLIENT_SECRET=xxx \
KEKA_API_KEY=xxx \
node dist/index.jsHealth check: GET http://localhost:3000/health
MCP endpoint: POST http://localhost:3000/mcp
Authentication
Keka uses a custom OAuth2 flow (grant_type=kekaapi). The server:
Fetches a Bearer token on first request
Caches the token in memory
Auto-refreshes 2 minutes before expiry (tokens last 24 hours)
Rate Limits
Keka enforces 50 requests per minute. The server returns a clear error message if this limit is hit.
Development
# Watch mode (no build required)
npm run dev
# Build
npm run build
# Start production
npm startAvailable Tools
17 toolskeka_create_leave_requestCreate Keka Leave RequestA
Submit a new leave request for an employee in Keka.
Args:
employeeId (string, required): Keka employee ID for whom leave is being requested
leaveTypeId (string, required): Leave type ID (use keka_list_leave_types to find IDs)
fromDate (string, required): Start date in ISO 8601 format (e.g., '2025-04-01')
toDate (string, required): End date in ISO 8601 format (e.g., '2025-04-03')
fromSession (number, optional): Start session — 0 = first half, 1 = second half (default: 0)
toSession (number, optional): End session — 0 = first half, 1 = second half (default: 1)
reason (string, optional): Reason for leave
note (string, optional): Additional note for the request
requestedBy (string, optional): Employee ID of the person submitting on behalf (defaults to employee)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Confirmation of leave request creation with the generated request ID.
Note: Requires the API key to have leave management write permissions.
Inputs: toDate (required), fromDate (required), employeeId (required), leaveTypeId (required), +6 more.
keka_get_attendanceGet Keka Attendance RecordsARead-onlyIdempotent
Retrieve attendance records for employees from Keka.
The Keka API supports a maximum date range of 90 days per request and defaults to the last 30 days.
Args:
employeeIds (string, optional): Comma-separated employee IDs to filter records
from (string, optional): Start date in ISO 8601 format (e.g., '2025-03-01'). Max 90-day range.
to (string, optional): End date in ISO 8601 format (e.g., '2025-03-31'). Max 90-day range.
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Attendance records per employee per day — clock-in, clock-out, total hours, shift, and status (Present, Absent, Half-Day, etc.).
Examples:
View attendance for a team this month → from='2025-03-01', to='2025-03-31', employeeIds='id1,id2'
Check if an employee was present → employeeIds='emp123', from='2025-03-10', to='2025-03-10'
Inputs: to, from, pageSize, pageNumber, +2 more.
keka_get_employeeGet Keka Employee DetailsARead-onlyIdempotent
Retrieve full details for a single employee by their Keka employee ID.
Args:
employeeId (string, required): The Keka employee ID (use keka_list_employees to find IDs)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Complete employee profile including personal info, department, job title, manager, location, and employment details.
Inputs: employeeId (required), response_format.
keka_get_leave_balancesGet Keka Leave BalancesARead-onlyIdempotent
Retrieve leave balances for employees in Keka.
Args:
employeeIds (string, optional): Comma-separated employee IDs (omit for all employees)
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Leave balance breakdown per employee and leave type — opening, earned, taken, pending, and closing balances.
Inputs: pageSize, pageNumber, employeeIds, response_format.
keka_list_candidatesList Keka Job CandidatesARead-onlyIdempotent
Retrieve candidates for a specific job opening in Keka Hire.
Args:
jobId (string, required): The Keka job ID (use keka_list_jobs to find IDs)
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Candidate list with name, email, phone, current interview stage, application date, source, and status.
Inputs: jobId (required), pageSize, pageNumber, response_format.
keka_list_departmentsList Keka DepartmentsARead-onlyIdempotent
Retrieve all departments defined in Keka HRM.
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: List of departments with IDs, names, parent department, and department lead.
Inputs: pageSize, pageNumber, response_format.
keka_list_employeesList Keka EmployeesARead-onlyIdempotent
Retrieve a paginated list of employees from Keka HRM.
Supports filtering by employment status, employee IDs, probation status, notice period, and a free-text search key.
Args:
employmentStatus (string, optional): Filter by status — 'Active', 'InActive', 'Terminated', 'NotJoined'
employeeIds (string, optional): Comma-separated employee IDs to fetch specific employees
searchKey (string, optional): Free-text search across name, email, employee number
inProbation (boolean, optional): Filter employees currently in probation
inNoticePeriod (boolean, optional): Filter employees in notice period
pageNumber (integer): Page number, starting at 1 (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Paginated list of employees with ID, name, email, department, job title, status, and join date.
Examples:
List all active employees → employmentStatus='Active'
Find a specific person → searchKey='John Doe'
Get employees by IDs → employeeIds='emp1,emp2,emp3'
Inputs: pageSize, searchKey, pageNumber, employeeIds, +4 more.
keka_list_groupsList Keka GroupsARead-onlyIdempotent
Retrieve all groups (teams/divisions) configured in Keka HRM.
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: List of groups with IDs, names, and types.
Inputs: pageSize, pageNumber, response_format.
keka_list_jobsList Keka Job OpeningsARead-onlyIdempotent
Retrieve all job openings from Keka Hire (Recruitment module).
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Job openings with ID, title, department, location, status, number of openings, posted date, closing date, and hiring manager.
Use keka_list_candidates to see candidates for a specific job.
Inputs: pageSize, pageNumber, response_format.
keka_list_job_titlesList Keka Job TitlesARead-onlyIdempotent
Retrieve all job titles configured in Keka HRM.
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: List of job titles with their IDs and names.
Inputs: pageSize, pageNumber, response_format.
keka_list_leave_requestsList Keka Leave RequestsARead-onlyIdempotent
Retrieve leave requests from Keka with optional filters for employees and date range.
Args:
employeeIds (string, optional): Comma-separated employee IDs to filter by
from (string, optional): Start date in ISO 8601 format (e.g., '2025-01-01')
to (string, optional): End date in ISO 8601 format (e.g., '2025-01-31')
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: List of leave requests with employee, leave type, dates, number of days, status, and reason.
Examples:
View pending leaves for a team → pass employeeIds and a date range
See who is on leave this month → from='2025-03-01', to='2025-03-31'
Inputs: to, from, pageSize, pageNumber, +2 more.
keka_list_leave_typesList Keka Leave TypesARead-onlyIdempotent
Retrieve all leave types configured in Keka (e.g., Annual Leave, Sick Leave, Casual Leave).
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: List of leave types with ID, name, code, and whether they are paid leave. Use the returned IDs when creating leave requests with keka_create_leave_request.
Inputs: pageSize, pageNumber, response_format.
keka_list_pay_bandsList Keka Pay BandsARead-onlyIdempotent
Retrieve all salary pay bands configured in Keka.
Pay bands define compensation ranges for job levels or grades.
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Pay bands with ID, name, minimum and maximum salary amounts, and currency.
Inputs: pageSize, pageNumber, response_format.
keka_list_pay_groupsList Keka Pay GroupsARead-onlyIdempotent
Retrieve all payroll groups configured in Keka.
Pay groups define payroll cycles and are used to filter salary listings.
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: List of pay groups with IDs, names, and descriptions. Use IDs with keka_list_salaries to filter by pay group.
Inputs: pageSize, pageNumber, response_format.
keka_list_psa_clientsList Keka PSA ClientsARead-onlyIdempotent
Retrieve all clients from Keka's Professional Services Automation (PSA) module.
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: PSA client records with ID, name, email, phone, status, and creation date. Use returned IDs with keka_list_psa_projects to find projects for a client.
Inputs: pageSize, pageNumber, response_format.
keka_list_psa_projectsList Keka PSA ProjectsARead-onlyIdempotent
Retrieve projects from Keka's Professional Services Automation (PSA) module.
Args:
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: PSA projects with ID, name, client, status, start/end dates, budget, currency, and project manager.
Inputs: pageSize, pageNumber, response_format.
keka_list_salariesList Keka Employee SalariesARead-onlyIdempotent
Retrieve salary information for employees from Keka payroll.
⚠️ This tool returns sensitive compensation data. Ensure your API key has payroll read access.
Args:
employeeIds (string, optional): Comma-separated employee IDs to filter
payGroupIds (string, optional): Comma-separated pay group IDs to filter (use keka_list_pay_groups)
employmentStatus (string, optional): Filter by 'Active', 'InActive', 'Terminated', 'NotJoined'
pageNumber (integer): Page number (default: 1)
pageSize (integer): Results per page, max 200 (default: 100)
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: Employee salaries with CTC (Cost to Company), pay group, currency, and effective date.
Inputs: pageSize, pageNumber, employeeIds, payGroupIds, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool targets a distinct entity and action—employees, leave types, requests, balances, attendance, salaries, jobs, candidates, PSA clients/projects—so no two tools overlap in purpose. Descriptions also cross-reference related tools, reinforcing correct selection.
All tools use the keka_ prefix with a consistent list/get/create verb followed by a clear noun, making behavior predictable. The naming pattern is uniform throughout the server.
At 17 tools, the count slightly exceeds the typical 3–15 range, but it is justified by the breadth of Keka modules covered (HR, payroll, leave, attendance, recruitment, PSA). There are no redundant tools, and each entity serves a clear purpose.
The set provides strong read coverage across multiple modules and supports creating leave requests, but it lacks update/delete/approval actions for most entities—such as employee updates, leave approvals, or candidate workflow steps. This leaves notable lifecycle gaps for a full HRIS integration.
Maintenance
Related MCP Connectors
MCP server for Talenta — read employee, attendance, leave, payroll and recruitment data.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
MCP server for SmartHR — employees, departments, dependents and employee invitations.
MCP server for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
Related MCP Servers
AlicenseAqualityCmaintenanceMCP server enabling AI assistants to connect to Kula recruiting API for managing jobs, candidates, applications, webhooks, and more.84401 npmMIT- FlicenseAqualityDmaintenanceRead-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.153-
- AlicenseBqualityDmaintenanceA production-quality MCP server for the Deel API that enables managing global HR, payroll, contractors, invoices, payments, and compliance through 48 tools.48MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the HR platform 'МояКоманда' that enables AI assistants to access and interact with HR data like employees, teams, calendar, absences, requests, knowledge base, surveys, and more via its REST API.MIT