Employee Leave Management MCP Server
Connects to a Supabase PostgreSQL database to manage employee leave data, including employees, leave types, balances, and requests, enabling tools for checking balances, applying for leave, approvals, and history.
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., "@Employee Leave Management MCP Server How many annual leave days do I have left?"
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.
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 |
| All leave categories (Annual, Sick, Casual, ā¦) with default allocation |
| Active employees, optional department filter |
| Look up one employee by code or email |
| Remaining / used / total days by employee & year |
| Submit a leave request (validates balance & date overlaps) |
| All requests for an employee, filterable by year/status |
| Full details of a single request by ID |
| Employee withdraws a pending request |
| Manager approves ā auto-deducts days from balance |
| 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
Go to https://supabase.com and create a free project.
After the project is ready, go to Project Settings ā API and copy:
Project URL ā
SUPABASE_URLProject API Keys ā
anonpublic key (orservice_rolekey for full access) āSUPABASE_KEY
Step 2 ā Set up the database
In the Supabase Dashboard, open the SQL Editor ā New Query.
Paste the full contents of
setup_database.sqland 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-keyStep 4 ā Install dependencies
uv syncStep 5 ā Test interactively (without Claude Desktop)
#uv run fastmcp dev server.py
uv run python server.py
# Opens MCP Inspector at http://localhost:6274Connect to Claude Desktop
Locate the config file
OS | Path |
macOS |
|
Windows |
|
Linux |
|
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 runningpwdin the project folder.
Note: You may need to provide the full path to the
uvexecutable in thecommandfield. Runwhich uv(macOS/Linux) orwhere 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) |
|
User profile (all workspaces) | Run |
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
uvin"command". Runwhich uvto find it.
Start the server
Open the Command Palette (
Ctrl+Shift+P) and run MCP: List Servers.Select
employee-leaveand choose Start.When prompted, confirm you trust the server.
Open the Chat view (
Ctrl+Alt+I), switch to Agent mode, and theemployee-leavetools 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 daysYou: 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 | cancelledProject 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 fileAvailable Tools
10 toolsapply_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
Scored across 10 tools
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.
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.
10 tools is well-scoped for an employee leave management domain. Each tool serves a necessary purpose without unnecessary duplication or bloat.
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
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.
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
- FlicenseBqualityDmaintenanceA Model Context Protocol server that enables users to manage employee leave through natural language. It provides tools to check leave balances, apply for leave, and view leave history via Claude integration.3-
- FlicenseNot gradedqualityDmaintenanceEnables employees to check leave balance, apply for leave, and view leave history through natural language using Claude Desktop.-
- FlicenseBqualityDmaintenanceEnables managing employee leave requests (apply, view, list leaves) through Claude desktop using natural language.6-
- FlicenseNot gradedqualityDmaintenanceEnables managing employee leave requests, balances, and approvals through natural language with Claude Desktop, using SQLite for persistence and fuzzy name matching.-