Leave Management

A simple Model Context Protocol (MCP) server that exposes employee leave-management operations (apply, cancel, check balance, view history) as tools an AI client (like Claude Desktop, Claude Code, or the MCP Inspector) can call directly.

Built as a learning project for understanding how MCP servers work — how tools are defined, registered, and invoked by an LLM client — before extending it into a real backend (e.g. with persistent storage).

---

Features

• Add new employees with a default leave balance
• Check an employee's remaining leave balance
• Apply for leave (with automatic balance deduction and history logging)
• View an employee's full leave history
• Cancel a previously applied leave (restores balance)
• List all employees in the system

Note: Data is stored in-memory for this version — it resets every time the server restarts. Persistence (SQLite/Postgres) is a planned next step.

---

Tech Stack

• Python 3.10+
• mcp (Python MCP SDK, FastMCP)
• uv for environment and dependency management

---

Project Structure

mcp-leave-management/
├── leave_server.py      # MCP server with all tool definitions
├── pyproject.toml       # Project metadata & dependencies (created by uv)
├── README.md
└── .gitignore

---

Setup

1. Clone the repository

git clone <your-repo-url>
cd mcp-leave-management

2. Install dependencies with uv

uv init --no-workspace
uv add "mcp[cli]"

3. Run the server with MCP Inspector (for manual testing)

uv run mcp dev leave_server.py

This opens the MCP Inspector in your browser, where you can connect to the server and call each tool manually with test inputs.

---

Available Tools

Tool	Parameters	Description
add_employee	employee_name: str	Adds a new employee with a default balance of 10 days
get_leave_balance	emp_name: str	Returns the employee's remaining leave balance
apply_leave	emp_name: str, days: int, reason: str	Deducts leave days and logs the request in history
get_leave_history	emp_name: str	Returns the list of past leave applications
cancel_leave	emp_name: str, leave_id: str	Cancels a leave entry and restores the balance
list_employees	—	Returns a list of all employee names

Default seed data

Employee	Starting Balance
Chandu	10
Sekhar	15

---

Example Usage (via MCP Inspector)

1. Call list_employees → confirms ["Chandu", "Sekhar"]
2. Call get_leave_balance with emp_name="Chandu" → returns 10
3. Call apply_leave with emp_name="Chandu", days=2, reason="Personal" → returns a confirmation message and deducts the balance
4. Call get_leave_balance again for Chandu → returns 8
5. Call get_leave_history for Chandu → shows the applied leave entry with its id
6. Call cancel_leave with that leave_id → restores the balance back to 10

---

Connecting to Claude Desktop / Claude Code

Once verified in the Inspector, this server can be registered as an MCP tool in a client's configuration (e.g. claude_desktop_config.json), pointing to the uv run command for leave_server.py.

---

Roadmap / Next Steps

• Replace in-memory dict with persistent storage (SQLite or Postgres)
• Input validation (e.g. reject negative/zero days in apply_leave)
• Role-based access (manager approval flow for leave requests)
• Unit tests for each tool
• Docker support for deployment

---

License

MIT (or update as preferred)