Skip to main content
Glama
Employee Leave Management MCP Server

Employee Leave Management MCP Server

Employee Leave Management — MCP Server

šŸ“Œ Check out GenAI and System Design videos

An MCP (Model Context Protocol) server built with FastMCP that connects to a Supabase PostgreSQL database and lets Claude Desktop manage employee leave — checking balances, applying for leave, approvals, history, and more.


Architecture

ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│  Claude Desktop (MCP Host)                            │
│                                                       │
│  "How many leaves does EMP001 have left this year?"   │
│                                                       │
│  Claude ──► get_leave_balance("EMP001", 2025)         │
│          ◄── [{Annual: 13 remaining}, {Sick: 8}, …]   │
│                                                       │
│  Claude: "Aditya has 13 Annual, 8 Sick, and 5 Casual  │
│           leave days remaining for 2025."             │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
          │ stdio (subprocess)
          ā–¼
ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”        ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│  server.py          │        │  Supabase (Postgres)  │
│  FastMCP + tools    │◄──────►│  employees            │
│                     │  REST  │  leave_types          │
│                     │  API   │  leave_balances       │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜        │  leave_requests       │
                               ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜

Related MCP server: leave-management

Exposed Tools

Tool

What it does

list_leave_types

All leave categories (Annual, Sick, Casual, …) with default allocation

list_employees

Active employees, optional department filter

get_employee_info

Look up one employee by code or email

get_leave_balance

Remaining / used / total days by employee & year

apply_for_leave

Submit a leave request (validates balance & date overlaps)

get_leave_history

All requests for an employee, filterable by year/status

get_leave_request

Full details of a single request by ID

cancel_leave_request

Employee withdraws a pending request

approve_leave_request

Manager approves — auto-deducts days from balance

reject_leave_request

Manager rejects with optional note

Resources

  • leave://schema — full schema overview attachable as context

Prompts

  • leave_assistant — structured conversation starter for the HR assistant


Quick Start

Step 1 — Create a Supabase project

  1. Go to https://supabase.com and create a free project.

  2. After the project is ready, go to Project Settings → API and copy:

    • Project URL → SUPABASE_URL

    • Project API Keys → anon public key (or service_role key for full access) → SUPABASE_KEY

Step 2 — Set up the database

  1. In the Supabase Dashboard, open the SQL Editor → New Query.

  2. Paste the full contents of setup_database.sql and click Run.

This creates four tables (employees, leave_types, leave_balances, leave_requests) plus a convenience view (leave_balances_view) and seeds 8 employees with realistic 2025 balances.

Step 3 — Configure environment variables

cd demo_projects/mcp
cp .env.example .env
# Edit .env with your Supabase URL and Key

.env contents:

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_KEY=your-anon-or-service-role-key

Step 4 — Install dependencies

uv sync

Step 5 — Test interactively (without Claude Desktop)

#uv run fastmcp dev server.py
uv run python server.py
# Opens MCP Inspector at http://localhost:6274

Connect to Claude Desktop

Locate the config file

OS

Path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

Add the server block

{
  "mcpServers": {
    "employee-leave": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/project_root",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Important: Use the absolute path in --directory. You can get it by running pwd in the project folder.

Note: You may need to provide the full path to the uv executable in the command field. Run which uv (macOS/Linux) or where uv (Windows) to find it.

Restart Claude Desktop

Quit and reopen Claude Desktop. Click the + ("Add files, connectors, and more") icon in the chat input area, then hover over Connectors — you should see employee-leave listed there.

Note: Claude for Desktop is not yet available on Linux. Linux users can use the MCP Inspector or build a custom MCP client instead.


Connect to VS Code (GitHub Copilot)

VS Code supports MCP servers natively through GitHub Copilot agent mode. The config format is different from Claude Desktop.

Locate / create the config file

Scope

File

Workspace (team-shared)

.vscode/mcp.json in your project root

User profile (all workspaces)

Run MCP: Open User Configuration from the Command Palette

Add the server block

Create or edit .vscode/mcp.json:

{
  "servers": {
    "employee-leave": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/project_root",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Note: VS Code uses "servers" (not "mcpServers") and requires the "type": "stdio" field. Use the absolute path in --directory.

Tip: You may need to provide the full path to uv in "command". Run which uv to find it.

Start the server

  1. Open the Command Palette (Ctrl+Shift+P) and run MCP: List Servers.

  2. Select employee-leave and choose Start.

  3. When prompted, confirm you trust the server.

  4. Open the Chat view (Ctrl+Alt+I), switch to Agent mode, and the employee-leave tools will be available.

Verify tools are loaded

In the Chat view, select Configure Tools (or the tools icon) to see all tools provided by the employee-leave server and toggle individual tools on/off.

Troubleshooting

If the server fails to start, run MCP: List Servers → select the server → Show Output to view logs.


Example Conversations with Claude

You: How many leaves does Aditya have left for 2025?

Claude: [calls get_employee_info("EMP001"), then get_leave_balance("EMP001", 2025)]
        Aditya Sharma (EMP001) has:
        • Annual leave  : 13 days remaining (5 used of 18)
        • Sick leave    :  8 days remaining (2 used of 10)
        • Casual leave  :  5 days remaining (1 used of 6)
You: Apply for annual leave for EMP002 from 10th July to 18th July 2025.

Claude: [calls apply_for_leave("EMP002", "Annual", "2025-07-10", "2025-07-18")]
        Leave request submitted!
        • Employee   : Priya Nair (EMP002)
        • Type       : Annual
        • Dates      : 10 Jul – 18 Jul 2025  (7 business days)
        • Status     : Pending
        • Remaining after approval: 8 Annual days
You: Approve request ID 3.

Claude: [calls approve_leave_request(3)]
        Leave request #3 has been approved. 7 days deducted from Priya's Annual balance.

Database Schema

employees          -- employee_code, full_name, email, department, position
leave_types        -- name, description, default_days
leave_balances     -- one row per (employee, leave_type, year)
leave_balances_view -- denormalised view with remaining_days computed
leave_requests     -- status: pending | approved | rejected | cancelled

Project Files

demo_projects/mcp/
ā”œā”€ā”€ server.py             ← FastMCP server (all tools, resources, prompts)
ā”œā”€ā”€ setup_database.sql    ← Run once in Supabase SQL Editor
ā”œā”€ā”€ pyproject.toml        ← Dependencies (fastmcp, supabase, python-dotenv)
ā”œā”€ā”€ .env.example          ← Copy to .env and fill in credentials
└── README.md             ← This file

Available Tools

10 tools
apply_for_leaveA

Submit a leave request on behalf of an employee.

Args: identifier: Employee code (e.g. "EMP001") or email. leave_type: Type of leave — use list_leave_types() for valid values (e.g. "Annual", "Sick", "Casual"). start_date: First day of leave in YYYY-MM-DD format. end_date: Last day of leave in YYYY-MM-DD format. reason: Optional reason for the leave request.

Inputs: end_date (required), identifier (required), leave_type (required), start_date (required), +1 more. Returns: object

approve_leave_requestA

Approve a pending leave request and deduct days from the employee's balance. Call this only when acting as an HR manager or team lead.

Args: request_id: Numeric ID of the leave request to approve. manager_note: Optional note from the manager (visible to the employee).

Inputs: request_id (required), manager_note. Returns: object

cancel_leave_requestA

Cancel a pending leave request. Only the employee who applied can cancel.

Args: request_id: Numeric ID of the leave request to cancel. identifier: Employee code or email of the requester (for authorisation).

Inputs: identifier (required), request_id (required). Returns: object

get_employee_infoB

Fetch details for a single employee.

Args: identifier: Employee code (e.g. "EMP001") or email address.

Inputs: identifier (required). Returns: object

get_leave_balanceA

Return the leave balance (total / used / remaining) for all leave types for the specified employee and year.

Args: identifier: Employee code or email. year: Calendar year (e.g. 2025). Defaults to the current year.

Inputs: identifier (required), year. Returns: result

get_leave_historyA

Retrieve all leave requests for an employee, optionally filtered by year or status.

Args: identifier: Employee code or email. year: Filter by calendar year. 0 = all years. status: Filter by status: "pending", "approved", "rejected", "cancelled". Leave empty to return all statuses.

Inputs: identifier (required), year, status. Returns: result

get_leave_requestA

Fetch full details of a single leave request by its ID.

Args: request_id: The numeric ID of the leave request (returned by apply_for_leave or get_leave_history).

Inputs: request_id (required). Returns: object

list_employeesA

List all active employees, optionally filtered by department.

Args: department: Filter by department name (partial match, case-insensitive). Leave empty to return all employees.

Inputs: department. Returns: result

list_leave_typesA

Return all available leave categories with their yearly default allocation. Call this to know valid leave_type values before applying for leave.

Inputs: no named parameters. Returns: result

reject_leave_requestA

Reject a pending leave request. Call this only when acting as an HR manager or team lead.

Args: request_id: Numeric ID of the leave request to reject. manager_note: Reason for rejection (recommended — visible to employee).

Inputs: request_id (required), manager_note. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct action (apply, approve, cancel, reject, retrieve info/balance/history/requests, list employees/types) with no overlap. Clear boundaries between approval workflow and information retrieval.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (e.g., apply_for_leave, get_leave_balance, list_employees). No deviations or mixing of styles.

    Tool Count5/5

    10 tools is well-scoped for an employee leave management domain. Each tool serves a necessary purpose without unnecessary duplication or bloat.

    Completeness4/5

    Covers the core lifecycle (apply, approve, reject, cancel) and read operations (balance, history, employee info). Minor gap: no tool to update a pending leave request (e.g., change dates or reason).

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    • CharlieHR MCP server for ChatGPT, Claude and any AI agent: list team members, list time off requests, approve time off request, deny time off request, book time off, record sick day, adjust time off allowance and cancel time off booking in your own CharlieHR account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to CharlieHR yourself; Cotlet does not store your password and you need no CharlieHR API key. About the official CharlieHR API: CharlieHR has an API, but a narrow one, and no official MCP server (checked 20 Oct 2026). A Super Admin creates a Client ID and Client Secret under Company > Integrations > API Access; the API covers team members, leave, offices and teams. Setup and FAQ: https://cotlet.dev/integrations/charliehr-api-mcp-server

    • Timetastic MCP server for ChatGPT, Claude and any AI agent: list wallchart absences, list pending leave requests, approve leave request, decline leave request, book time off, cancel booking, get monthly leave summary and get annual allowance summary in your own Timetastic account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Timetastic yourself; Cotlet does not store your password and you need no Timetastic API key. About the official Timetastic API: Yes, Timetastic has a REST API with a bearer token, and no official MCP server (checked 20 Oct 2026). Only admin users can get a token, and the API has no endpoints for the monthly and annual summary reports. Setup and FAQ: https://cotlet.dev/integrations/timetastic-api-mcp-server

    • Employee leave and PTO: requests, approvals, balances, who is out, and conflict checks.

      https://mcp.zovo.one/mcp/leave
    • BambooHR MCP server for ChatGPT, Claude and any AI agent: request time off, approve time off, update employee, create onboarding task, get report and list employees in your own BambooHR account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to BambooHR yourself; Cotlet does not store your password and you need no BambooHR API key. About the official BambooHR API: Yes. BambooHR has a public REST API (API key or OAuth) and a beta MCP server at {your-subdomain}.bamboohr.com/api/mcp that an admin must switch on under Settings > Apps > AI Connectors (checked 16 Oct 2026). Setup and FAQ: https://cotlet.dev/integrations/bamboohr-api-mcp-server

    Related MCP Servers