pravinkpk30/mcp-server-hr
If you are the rightful owner of mcp-server-hr 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.
The Model Context Protocol (MCP) server is a specialized server designed to facilitate communication and data exchange between machine learning models and various client applications.
Leave Management MCP Server
A Model Context Protocol (MCP) server for managing employee leave requests. This server provides a simple API to check leave balances, apply for leave, and view leave history for employees.
Features
- Check available leave balance for employees
- Apply for leave with specific dates
- View leave history
- Simple in-memory storage (resets on server restart)
- FastAPI-based REST API
Prerequisites
- Python 3.11 or higher
- UV package manager (recommended) or pip
Installation
Build Your First MCP Server: Leave Management
This AI tool helps an HR with leave management related tasks. The codebase here is for MCP server that interacts with mock leave database and responds to MCP client queries
Setup steps
- Install Claude Desktop
- Install uv by running
pip install uv
- Run
uv init mcp-server-hr
to create a project directory - Run
uv add "mcp[cli]"
to add mcp cli in your project - Few folks may get type errors for which you can run
pip install --upgrade typer
to upgrade typer library to its latest version - Write code in main.py for leave management server
- Install this server inside Claude desktop by running
uv run mcp install main.py
in the project directory - Kill any running instance of Claude from Task Manager. Restart Claude Desktop
- In Claude desktop, now you will see tools from this server
Using UV Package Manager (Recommended)
-
Install UV if you haven't already:
curl -LsSf https://astral.sh/uv/install.sh | sh
-
Clone the repository:
git clone https://github.com/praveenkumar/mcp-server-hr.git cd mcp-server-hr
-
Create and activate a virtual environment:
uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
-
Install dependencies:
uv pip install -e .
Using pip
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .
Running the Server
uvicorn main:app --reload
The server will start at http://127.0.0.1:8000
by default.
API Endpoints
1. Check Leave Balance
Endpoint: GET /get_leave_balance
Parameters:
employee_id
(string, required): Employee ID to check balance for
Example Request:
curl "http://127.0.0.1:8000/get_leave_balance?employee_id=E001"
Example Response:
"E001 has 18 leave days remaining."
2. Apply for Leave
Endpoint: POST /apply_leave
Parameters:
employee_id
(string, required): Employee IDleave_dates
(array of strings, required): List of dates in YYYY-MM-DD format
Example Request:
curl -X POST "http://127.0.0.1:8000/apply_leave" \
-H "Content-Type: application/json" \
-d '{"employee_id":"E002", "leave_dates":["2025-08-01","2025-08-02"]}'
Example Response:
"Leave applied for 2 day(s). Remaining balance: 18."
3. Get Leave History
Endpoint: GET /get_leave_history
Parameters:
employee_id
(string, required): Employee ID
Example Request:
curl "http://127.0.0.1:8000/get_leave_history?employee_id=E001"
Example Response:
"2024-12-25, 2025-01-01"
Available Employee IDs
E001
: Initial balance of 18 daysE002
: Initial balance of 20 days
For Claude Desktop
Prerequisites
- Install Claude Desktop from the official Anthropic website
- Python 3.11+ and pip installed
Setup Steps
Install UV Package Manager:
pip install uv
Initialize a new MCP project:
uv init my-leave-mcp
cd my-leave-mcp
Install MCP CLI:
uv add "mcp[cli]"
Install Typer (if needed):
pip install --upgrade typer
Install the MCP Server:
mcp install main.py
Restart Claude Desktop:
- Close Claude Desktop completely
- Reopen Claude Desktop Verification:
- Start a new conversation
- You should see the Leave Management tools available
For Windsurf
Prerequisites
- Windsurf application installed
- MCP server running locally
Setup Steps
Start the MCP Server:
uvicorn main:app --reload
Configure Windsurf:
- Open Windsurf settings
- Go to "MCP Servers" section
- Click "Add New Server"
- Enter: http://127.0.0.1:8000
- Name it "Leave Management"
- Save the configuration
- Verify Connection: The Leave Management tools should now be available in Windsurf
Common Issues & Solutions
Tools Not Appearing
- Ensure you've restarted the application after installation
- Check if the MCP server is running
- Verify the installation command completed successfully
Connection Issues
- Confirm the server URL is correct
- Check if the port (default: 8000) is available
- Look for any firewall/network restrictions
Type Errors
pip install --upgrade typer
Development
Project Structure
main.py
: Main application file with all API endpointspyproject.toml
: Project configuration and dependenciesuv.lock
: Lock file for reproducible builds with UV
Testing
To run tests (if available):
uv pip install pytest
pytest
License
This project is licensed under the MIT License - see the file for details.
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature
) - Commit your changes (
git commit -m 'Add some AmazingFeature'
) - Push to the branch (
git push origin feature/AmazingFeature
) - Open a Pull Request