Skip to main content
Glama

šŸ¤– 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        utils
  • MCP 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


1. Clone the Repository

git clone https://github.com/saibalajijammu/HR_helpdesk.git
cd HR_helpdesk

2. Install Dependencies

uv init
uv add mcp[cli]

3. Set Up Environment Variables

cp sample.env .env

Edit .env and fill in:

CB_EMAIL=your_email@gmail.com
CB_EMAIL_PWD=your_gmail_app_password

4. Configure Claude Desktop

Open your claude_desktop_config.json file and add the following:

Location of config file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Mac: ~/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

  1. Click the + icon in Claude Desktop

  2. Select Add from hr-assist

  3. Fill in the employee details when prompted

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

CB_EMAIL

Your Gmail address used for sending emails

CB_EMAIL_PWD

Gmail App Password (not your regular password)


🧰 Tech Stack

Component

Technology

AI Model

Claude (Anthropic)

MCP Client

Claude Desktop

MCP Server

Python + mcp[cli]

Package Manager

uv

Email

SMTP (Gmail)

Data Validation

Pydantic (schemas.py)


šŸ¤ 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 tools
add_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

    C2.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers