Keka MCP Server

A Model Context Protocol (MCP) server for integrating with the Keka HR platform. This server exposes Keka employee management, attendance, leave, payslip, and holiday APIs as MCP tools, with robust OAuth2 authentication and modular code structure.

Features

OAuth2 Authentication: Securely connects to Keka using OAuth2 credentials.
Tool-based API: Exposes Keka HR features as MCP tools for easy integration and automation.
Modular Structure: Clean, extensible TypeScript codebase modeled after best practices.
Docker Support: Ready-to-use Dockerfile for containerized deployment.

Environment Variables

Create a .env file in the project root with the following:

KEKA_CLIENT_ID=your_keka_client_id_here
KEKA_CLIENT_SECRET=your_keka_client_secret_here
KEKA_REFRESH_TOKEN=your_keka_refresh_token_here
# Optional:
KEKA_API_BASE_URL=https://master.kekademo.com/api/v1

Available Tools

1. `keka_get_employee_profile`

Get detailed profile information for a specific employee.

Arguments:
- employee_id (string, required): The UUID of the employee.
Example:

{
  "employee_id": "EMP123456"
}

2. `keka_get_attendance`

Get attendance records for an employee within a date range.

Arguments:
- employee_id (string, required)
- start_date (string, required, format: YYYY-MM-DD)
- end_date (string, required, format: YYYY-MM-DD)
- page (number, optional, default: 1)
- page_size (number, optional, default: 100)
Example:

{
  "employee_id": "EMP123456",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "page": 1,
  "page_size": 50
}

3. `keka_apply_leave`

Apply for leave for an employee.

Arguments:
- employee_id (string, required)
- start_date (string, required)
- end_date (string, required)
- leave_type (string, required, leave type UUID)
- reason (string, required)
Example:

{
  "employee_id": "EMP123456",
  "start_date": "2024-04-10",
  "end_date": "2024-04-12",
  "leave_type": "ANNUAL",
  "reason": "Family function"
}

4. `keka_get_leave_balances`

Get a consolidated view of all leave balances for an employee.

Arguments:
- employee_id (string, required)
Example:

{
  "employee_id": "EMP123456"
}

5. `keka_get_payslip`

Get payslip for an employee for a specific month and year.

Arguments:
- employee_id (string, required)
- month (string, required, e.g., "4" for April)
- year (string, required, e.g., "2024")
Example:

{
  "employee_id": "EMP123456",
  "month": "4",
  "year": "2024"
}

6. `keka_get_upcoming_holidays`

Get the list of upcoming company holidays.

Arguments: none
Example:

{}

7. `keka_view_leave_history`

View the leave history for an employee.

Arguments:
- employee_id (string, required)
- start_date (string, optional)
- end_date (string, optional)
- status (string, optional)
- page (number, optional, default: 1)
- page_size (number, optional, default: 100)
Example:

{
  "employee_id": "EMP123456",
  "start_date": "2024-01-01",
  "end_date": "2024-04-01",
  "status": "APPROVED",
  "page": 1,
  "page_size": 20
}

8. `keka_get_leave_types`

Get the list of available leave types.

Arguments: none
Example:

{}

Usage

Local (Node.js)

Install dependencies:
```
npm install
```
Build the TypeScript project:
```
npm run build
```
Start the MCP server:
```
node build/index.js
```

Docker

Build the Docker image:
```
docker build -t keka-mcp .
```
Run the container (using your .env file):
```
docker run --env-file .env keka-mcp
```

Project Structure

src/index.ts — Main MCP server implementation, tool definitions, Keka API integration.
.env — Environment variables for Keka OAuth2 credentials.
Dockerfile — Containerization support.
package.json — Project dependencies and scripts.

Contributing

Pull requests and issues are welcome! Please ensure any new tools or features follow the modular handler style and include robust error handling.

License

MIT

Reference

This project is generated and maintained with best practices for MCP integrations.