Darwinbox MCP

🚀 Darwinbox HRMS MCP Server

A Model Context Protocol (MCP) server for interacting with the Darwinbox HRMS API. This server provides standard interface tools for managing employee data, attendance, and leave management.

🎥 Demo

✨ Features

Core Tools

• Employee Management
  • Retrieve detailed information of employees (single, multiple, or all employees)
  • Update employee information
  • Add new employees
  • Deactivate employees
  • Download personal documents
  • Retrieve employee history
  • Retrieve position master data
  • Retrieve form data
  • Retrieve separation details
  • Upload profile attachments

Attendance Management Tools

• Attendance Management
  • Retrieve monthly attendance records
  • Retrieve daily attendance records
  • Retrieve roster attendance
  • Record attendance punches
  • Record retroactive attendance
• Leave Management
  • Approve leave requests
  • Retrieve leave operation history
  • Retrieve the leave list
  • Retrieve leave balances
  • Import leave records

📦 Installation

1. Clone the repository:

git clone https://github.com/prithvidbox/darwinbox-mcp
cd darwinbox-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

💻 MCP Client Configuration

Claude Desktop Client Configuration

{
  "mcpServers": {
    "darwinbox": {
      "command": "node",
      "args": ["path/to/darwinbox-server/build/index.js"],
      "env": {
        "DARWINBOX_DOMAIN": "https://your-domain.darwinbox.in",
        "DARWINBOX_CLIENT_ID": "your-client-id",
        "DARWINBOX_CLIENT_SECRET": "your-client-secret",
        "DARWINBOX_GRANT_TYPE": "authorization_code",
        "DARWINBOX_CODE": "your-auth-code",
        "DARWINBOX_DATASET_KEY": "your-dataset-key"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cline Configuration

{
  "servers": {
    "darwinbox": {
      "command": "node",
      "args": ["path/to/darwinbox-server/build/index.js"],
      "env": {
        "DARWINBOX_DOMAIN": "https://your-domain.darwinbox.in",
        "DARWINBOX_CLIENT_ID": "your-client-id",
        "DARWINBOX_CLIENT_SECRET": "your-client-secret",
        "DARWINBOX_GRANT_TYPE": "authorization_code",
        "DARWINBOX_CODE": "your-auth-code",
        "DARWINBOX_DATASET_KEY": "your-dataset-key"
      }
    }
  }
}

Cursor Configuration

{
  "mcpServers": {
    "darwinbox": {
      "command": "node",
      "args": ["path/to/darwinbox-server/build/index.js"],
      "env": {
        "DARWINBOX_DOMAIN": "https://your-domain.darwinbox.in",
        "DARWINBOX_CLIENT_ID": "your-client-id",
        "DARWINBOX_CLIENT_SECRET": "your-client-secret",
        "DARWINBOX_GRANT_TYPE": "authorization_code",
        "DARWINBOX_CODE": "your-auth-code",
        "DARWINBOX_DATASET_KEY": "your-dataset-key"
      }
    }
  }
}

🔐 Authentication

The server uses OAuth 2.0 for authentication. It automatically handles:

1. Obtaining tokens using the provided credentials
2. Token management and renewal
3. Authenticated API requests with appropriate headers

❌ Error Handling

The server provides detailed error messages, including:

• Missing or invalid configuration
• Authentication failure
• Invalid API requests
• API response errors

📄 License

This project is released under the MIT License. For more details, please refer to the LICENSE file.