itsmistahji-leave-management-mcp
If you are the rightful owner of itsmistahji-leave-management-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
This repository contains a Model Context Protocol (MCP) server for managing employee leave in an organization.
Leave Management MCP Server
This repository contains a Model Context Protocol (MCP) server for managing employee leave in an organization. The server integrates with Excel workbooks containing employee leave data and provides tools for querying and analyzing leave records.
Table of Contents
- Prerequisites
- Project Structure
- Installation
- Configuration
- Running the Server
- Troubleshooting
- Example Queries
Prerequisites
- Python 3.9+
- UV package manager
- Claude Desktop (or another MCP client)
- Excel workbook with leave data
Project Structure
leave-management-mcp/
├── src/
│ ├── __init__.py
│ ├── config.py # Configuration settings
│ ├── leave_server.py # Main MCP server
│ ├── data_manager.py # Data processing module
│ └── models/
│ ├── __init__.py
│ └── employee.py # Employee data models
├── data/
│ └── leave_tracker.xlsx # Excel workbook with leave data
├── main.py # Entry point wrapper
├── __init__.py # Root package marker
├── requirements.txt # Dependencies
└── README.md # Project documentation
Installation
- Clone this repository:
git clone https://github.com/ItsMistahJi/itsmistahji-leave-management-mcp.git
cd leave-management-mcp
- Set up the Python environment with UV:
pip install uv
uv init .
- Install dependencies:
uv add "mcp[cli]" pandas openpyxl python-dotenv PyPDF2
Configuration
- Create a
.envfile in the project root:
DATA_DIR=/path/to/your/data/directory
EXCEL_FILE=/path/to/your/data/directory/leave_tracker.xlsx
SERVER_NAME=LeaveManagement
DEBUG_MODE=True
- Ensure your Excel workbook has the correct structure:
- A sheet named "Leaves-2025" (or modify
data_manager.pyto use your sheet name) - Columns for "Sl No", "Name", "EMP ID", "Location", and month names ("Jan", "Feb", etc.)
- A sheet named "Leaves-2025" (or modify
Running the Server
Local Development Testing
# Test the server locally
uv run python -m src.leave_server
# Install in Claude Desktop for testing
uv run mcp install src/leave_server.py --name "Leave Management"
VS Code Integration
Add this configuration to your VS Code settings:
"mcpServers": {
"LeaveManagement": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--with",
"mcp[cli],pandas,openpyxl,python-dotenv,PyPDF2",
"mcp",
"run",
"/path/to/leave-management-mcp/src/leave_server.py"
]
}
}
[
Note: Replace /path/to/leave-management-mcp with your actual project path.
Troubleshooting
"No module named 'src'" Error
This error occurs when Python can't find the 'src' package in its module search path.
Solutions:
- Add
__init__.pyfiles to make src a proper package:
touch __init__.py
touch src/__init__.py
touch src/models/__init__.py
- Modify your server script (leave_server.py) to include the path:
import sys
import os
sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
- Use the main.py wrapper in the root directory:
import sys
import os
sys.path.insert(0, os.path.abspath('.'))
from src.leave_server import mcp
if __name__ == "__main__":
mcp.run()
"No module named 'pandas'" Error
This occurs when the environment running your server doesn't have pandas installed.
Solutions:
- Ensure all dependencies are installed in the same environment:
uv add pandas openpyxl python-dotenv PyPDF2
- Use the
--withflag when running the server:
uv run --with "mcp[cli],pandas,openpyxl,python-dotenv,PyPDF2" mcp run src/leave_server.py
Excel Data Loading Issues
If you encounter validation errors with Excel data:
- Review and modify the
load_datafunction indata_manager.pyto match your Excel structure - Ensure the sheet name matches your Excel file
- Check column names and handle NaN values properly
Example Queries
Once your server is running, you can ask Claude:
- "Who is on leave today?"
- "Show me the leave balance for employee 12345"
- "List all employees on leave in April"
- "Get leave details for Arun S"
- "When did Jeeva Rao take leave in March?"
Finding Logs for Debugging
- Claude Desktop Logs:
- macOS:
~/Library/Logs/Claude/mcp.log - Windows:
%APPDATA%\Claude\logs\mcp.log
- macOS:
- Print Statements: Any
print()statements in your server code will appear in the logs.
