HR-Assist
Sends welcome emails with credentials via Gmail SMTP using an App Password.
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., "@HR-Assist Onboard new employee Alice under manager Bob"
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.
š¤ HR-Assist ā Agentic AI HR Helpdesk
HR-Assist is an Agentic AI system that helps HR teams automate routine workflows using Claude Desktop as the MCP client and a custom Python MCP server as the backend.
This project demonstrates end-to-end automation of the employee onboarding process ā tasks that typically require multiple manual steps are handled by the AI agent in a single prompt.
⨠What It Does
Task | Automated? |
Add employee to HRMS | ā |
Send welcome email with credentials | ā |
Notify the manager | ā |
Raise tickets for laptop, ID card & equipment | ā |
Schedule introductory meeting | ā |
Leave management | ā |
Ticket tracking & updates | ā |
Related MCP server: HR-ASSIST
šļø Architecture
āāāāāāāāāāāāāāāāāāāāāāā MCP Protocol āāāāāāāāāāāāāāāāāāāāāāā
ā ā āāāāāāāāāāāāāāāāāāāāāāāāāāāŗ ā ā
ā Claude Desktop ā ā HR-Assist Server ā
ā (MCP Client) ā ā (Python + uv) ā
ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāā
ā
āāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāā
ā¼ ā¼ ā¼
employee_manager leave_manager ticket_manager
meeting_manager schemas utilsMCP Client ā Claude Desktop
MCP Server ā This codebase (
server.py+hrms/modules)Email ā SMTP via Gmail App Password
š Project Structure
HR_helpdesk/
ā
āāā hrms/
ā āāā __init__.py
ā āāā employee_manager.py # Add & fetch employee logic
ā āāā leave_manager.py # Leave apply, balance, history
ā āāā meeting_manager.py # Schedule & fetch meetings
ā āāā ticket_manager.py # Create & update tickets
ā āāā schemas.py # Pydantic data models
ā
āāā server.py # MCP server entry point
āāā utils.py # Shared utility functions
āāā emails.py # Email sending logic (SMTP)
āāā pyproject.toml # Project config (uv)
āāā sample.env # Environment variable template
āāā README.mdāļø Setup Instructions
Prerequisites
Claude Desktop installed
uv installed
Gmail account with App Password enabled
1. Clone the Repository
git clone https://github.com/saibalajijammu/HR_helpdesk.git
cd HR_helpdesk2. Install Dependencies
uv init
uv add mcp[cli]3. Set Up Environment Variables
cp sample.env .envEdit .env and fill in:
CB_EMAIL=your_email@gmail.com
CB_EMAIL_PWD=your_gmail_app_password4. Configure Claude Desktop
Open your claude_desktop_config.json file and add the following:
Location of config file:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonMac:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"hr-assist": {
"command": "C:\\Users\\<your-username>\\.local\\bin\\uv",
"args": [
"--directory",
"<full-path-to-project>\\HR_helpdesk",
"run",
"server.py"
],
"env": {
"CB_EMAIL": "YOUR_EMAIL",
"CB_EMAIL_PWD": "YOUR_APP_PASSWORD"
}
}
}
}Replace
<your-username>and<full-path-to-project>with your actual values.
5. Restart Claude Desktop
After saving the config, fully restart Claude Desktop. You should see hr-assist appear as a connected MCP server.
š¬ Usage
Option 1 ā Quick Onboarding via UI
Click the
+icon in Claude DesktopSelect
Add from hr-assistFill in the employee details when prompted
Option 2 ā Custom Prompt (Recommended)
Just type a natural language prompt like:
Onboard a new employee named Priya Mehta under manager Raj Kumar.The agent will automatically:
ā Add her to the HRMS
ā Send a welcome email
ā Notify her manager
ā Raise tickets for laptop, ID card & equipment
ā Schedule an intro meeting
š Environment Variables
Variable | Description |
| Your Gmail address used for sending emails |
| Gmail App Password (not your regular password) |
š§° Tech Stack
Component | Technology |
AI Model | Claude (Anthropic) |
MCP Client | Claude Desktop |
MCP Server | Python + |
Package Manager |
|
SMTP (Gmail) | |
Data Validation | Pydantic ( |
š¤ Contributing
Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.
š License
This project is licensed under the MIT License.
Available Tools
12 toolsadd_employeeC
Add a new employee to the HRMS system. :param emp_name: Employee name :param manager_id: Manager ID (optional) :return: Confirmation message
Inputs: email (required), emp_name (required), manager_id (required). Returns: result
apply_leaveA
Apply for leave for an employee. :param emp_id: Employee ID :param leave_dates: List of leave dates :return: Leave application status message
Inputs: emp_id (required), leave_dates (required). Returns: result
cancel_meetingC
Cancel a scheduled meeting for an employee. :param employee_id: Employee ID :param meeting_datetime: Date and time of the meeting in python datetime format :param topic: Topic of the meeting (optional) :return: Confirmation message
Inputs: topic (required), employee_id (required), meeting_datetime (required). Returns: result
create_ticketA
Create a ticket for buying required items for an employee. :param emp_id: Employee ID :param item: Item requested (Laptop, ID Card, etc.) :param reason: Reason for the request :return: Confirmation message
Inputs: item (required), emp_id (required), reason (required). Returns: result
get_employee_detailsB
Get employee details by name. :param name: Name of the employee :return: Employee ID and manager ID
Inputs: name (required). Returns: result
get_employee_leave_balanceB
Get the leave balance of an employee. :param emp_id: Employee ID :return: Leave balance message
Inputs: emp_id (required). Returns: result
get_leave_historyB
Get the leave history of an employee. :param emp_id: Employee ID :return: Leave history message
Inputs: emp_id (required). Returns: result
get_meetingsB
Get the list of meetings scheduled for an employee. :param employee_id: Employee ID :return: List of meetings
Inputs: employee_id (required). Returns: result
list_ticketsA
List tickets for an employee with optional status filter. :param employee_id: Employee ID :param status: Ticket status (optional) :return: List of tickets
Inputs: status (required), employee_id (required). Returns: result
schedule_meetingA
Schedule a meeting for an employee. :param employee_id: Employee ID :param meeting_datetime: Date and time of the meeting in python datetime format :param topic: Topic of the meeting :return: Confirmation message
Inputs: topic (required), employee_id (required), meeting_datetime (required). Returns: result
send_emailD
Inputs: body (required), subject (required), to_emails (required), html. Returns: result
update_ticket_statusB
Update the status of a ticket. :param ticket_id: Ticket ID :param status: New status of the ticket :return: Confirmation message
Inputs: status (required), ticket_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 12 tools
Each tool targets a distinct HR function: employee details, email, ticket lifecycle, meeting lifecycle, and leave management. Despite some overlapping resource types (e.g., tickets, meetings), the actions are clearly different and descriptions remove ambiguity.
Tool names mostly follow a snake_case verb_noun pattern, but there are inconsistencies: 'get_meetings' and 'list_tickets' both retrieve lists yet use different verbs, while 'add_employee' and 'create_ticket' both indicate creation. This mixed convention, though readable, is not fully predictable.
12 tools is well-scoped for an HR assistant covering employee, ticket, meeting, and leave management. Each tool earns its place, and the count is within the ideal range for a domain-specific server.
The set covers core actions (create, read, some update/delete) for each subdomain, but notable gaps exist: no employee update/delete, no meeting reschedule, and no leave cancellation. These missing lifecycle operations are significant but not severe enough to render the server unusable.
Maintenance
Related MCP Connectors
AI-powered corporate learning platform ā manage courses, users, and insights via Claude.
Describe your business to Claude and it builds your cockpit: a custom work tool with its assistant.
Connect your AI assistant to your Peak HR portal: HR operations, people, documents and drafts.
Ask Claude or ChatGPT about your team in PapaHR: who is away, hiring, probation, eNPS, HR costs.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables HR teams to query and manage employee leave through natural language using Claude Desktop, with tools for checking balances, applying leave, and viewing history.3-
- FlicenseBqualityDmaintenanceAgentic AI system that automates HR workflows like employee onboarding, enabling HR teams to streamline tasks through natural language interactions with Claude Desktop.12-
- FlicenseNot gradedqualityDmaintenanceEnables HR teams to automate employee onboarding workflows through an Agentic AI system integrated with Claude Desktop.1-
- AlicenseCqualityDmaintenanceEnables Claude Desktop to autonomously perform HR operations such as employee onboarding, leave management, meeting scheduling, ticket creation, and email notifications through MCP tool calling.12MIT