Kasra Lite Attendance & Personnel MCP Server

A Model Context Protocol (MCP) server for the Kasra Lite Attendance, Personnel, Cartable, and Leave Management System (app.kasralite.com).

Connect your AI agents (Claude Desktop, OpenCode, Cursor, Windsurf, etc.) directly to Kasra Lite to view attendance, punches, leaves, cardex, cartable requests, work periods, and submit leave/mission requests autonomously.

🚀 100% Pure HTTP & Async API — No Headless Browser Required!
Runs via standard HTTP/2 APIs and AES-128-CBC encryption without downloading Chromium or running Playwright/Puppeteer. Works in any environment including headless Linux servers, Docker containers, macOS, and Windows.

🌟 Available MCP Tools (17 Tools)

1. Personnel Profile & Dashboard

• kasra_get_profile: Retrieve user identity, personnel code, system ID, role, department, and recent login IP history.
• kasra_get_dashboard_summary: Real-time summary:
  • Last registered punch of today (time & status)
  • Cardex leave balance (hours)
  • Total presence & worked hours in current period
  • Permissions needed (incomplete punches, overtime, deficit)
  • Request approval counters (in progress, confirmed, rejected)
  • Pending cartable documents count
• kasra_get_desktop_shortcuts: Get user's pinned/favorite desktop bookmarks.
• kasra_get_messages: Retrieve broadcast announcements and system messages.

2. Attendance & Reports

• kasra_get_daily_report: Day-by-day detailed breakdown of punches, hours, shift, structure, surplus presence, and deficit presence with date filtering.
• kasra_get_monthly_report: Aggregate monthly attendance report with period selection.
• kasra_get_work_periods: List of all available financial and attendance work periods (e.g., Shahrivar 1405, Mordad 1405, ...).
• kasra_export_daily_report_excel: Generate and download daily attendance reports directly as an Excel (.xls) file.

3. Permissions, Leaves & Missions

• kasra_get_credit_types: List all permission types with codes:
  • Hourly deficit: Hourly leave (11001), Hourly sick leave (11011), Hourly mission (11021), Hourly remote work (14087), etc.
  • Daily deficit: Daily leave (11002), Daily sick leave (11012), Daily mission (11022), Daily remote work (14084), etc.
  • Surplus presence: Regular overtime (11101), Remote overtime (14088), Friday overtime (60023), etc.
• kasra_submit_credit_request: Submit a new hourly or daily leave, mission, remote work, or overtime request with automated security tokens.
• kasra_get_submitted_requests: View all submitted permission requests and their approval/rejection status.
• kasra_delete_credit_request: Cancel/delete a submitted permission request.

4. Cartable & Workflow

• kasra_get_cartable_items: View workflow documents in cartable by tab:
  • in_wait: Requests awaiting your approval
  • confirmed: Approved documents
  • rejected: Rejected documents
  • refer: Referred documents

5. System Base Information

• kasra_get_system_shifts: Retrieve all defined organizational shifts (Administrative shift, Remote work shift, etc.).
• kasra_get_personnel_groups: Retrieve all organizational personnel groups and permission categories.
• kasra_get_holidays: Official holiday calendar defined in the system.
• kasra_get_user_menu: Complete hierarchy of accessible system menus and subsystems.

📦 Installation

git clone https://github.com/razavioo/kasra-mcp-server.git
cd kasra-mcp-server
pip install -r requirements.txt

⚙️ Configuration

Copy the example environment file:

cp .env.example .env

Edit .env:

KASRA_BASE_URL=https://app.kasralite.com
KASRA_USERNAME=your_national_id_or_username
KASRA_PASSWORD=your_password

🔌 Agent Integration

You can run this MCP server either directly without cloning using uvx, via pip, or from a local clone.

Option A: Zero-Install with uvx (Recommended)

No need to clone the repo or manage python environments!

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "kasra": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/razavioo/kasra-mcp-server.git",
        "kasra-mcp-server"
      ],
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}

OpenCode (~/.config/opencode/opencode.jsonc or opencode.json)

{
  "mcp": {
    "kasra": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/razavioo/kasra-mcp-server.git",
        "kasra-mcp-server"
      ],
      "environment": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      },
      "enabled": true
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "kasra": {
      "command": "uvx --from git+https://github.com/razavioo/kasra-mcp-server.git kasra-mcp-server",
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}

Option B: Installed via pip

pip install git+https://github.com/razavioo/kasra-mcp-server.git

Then in your MCP configuration:

{
  "mcpServers": {
    "kasra": {
      "command": "kasra-mcp-server",
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}

Option C: From Local Source

git clone https://github.com/razavioo/kasra-mcp-server.git
cd kasra-mcp-server
pip install -r requirements.txt

{
  "mcpServers": {
    "kasra": {
      "command": "python3",
      "args": [
        "/path/to/kasra-mcp-server/main.py"
      ],
      "env": {
        "KASRA_BASE_URL": "https://app.kasralite.com",
        "KASRA_USERNAME": "your_username",
        "KASRA_PASSWORD": "your_password"
      }
    }
  }
}

🧪 Testing

Test all tools directly in python:

python3 test_tools.py

📄 License

This project is licensed under the MIT License.