Skip to main content
Glama

๐Ÿง‘โ€๐Ÿ’ผ HR Assist โ€” MCP Server

An MCP (Model Context Protocol) server that automates HR onboarding tasks โ€” HRMS registration, welcome emails, IT ticketing, meeting scheduling, and leave management โ€” so an AI agent like Claude can handle the entire new-hire workflow from a single prompt. ๐Ÿš€


โœจ Features

Area

What it does

๐Ÿ‘ค Employee Management

Add employees, fetch details by (fuzzy) name search, look up managers & direct reports

๐Ÿ“ง Email

Send plain-text or HTML emails (with optional attachments) via SMTP

๐ŸŽซ Ticketing

Raise, update, and list IT/equipment tickets (laptop, ID card, etc.)

๐Ÿ“… Meetings

Schedule, list, and cancel meetings for any employee

๐ŸŒด Leave Management

Check leave balance, apply for leave, view leave history

โšก Ready-made Prompt

Built-in onboard_new_employee MCP prompt that chains all of the above into one onboarding flow


Related MCP server: HRizzle-HR-Assist

๐Ÿ—‚๏ธ Project Structure

atliq-hr-assist/
โ”œโ”€โ”€ server.py              # FastMCP server โ€” defines all MCP tools & the onboarding prompt
โ”œโ”€โ”€ emails.py              # EmailSender โ€” SMTP email utility (plain/HTML + attachments)
โ”œโ”€โ”€ utils.py               # seed_services() โ€” seeds in-memory demo data
โ”œโ”€โ”€ HRMS/
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”œโ”€โ”€ employee_manager.py   # EmployeeManager โ€” employee CRUD + org hierarchy
โ”‚   โ”œโ”€โ”€ meeting_manager.py    # MeetingManager โ€” schedule/list/cancel meetings
โ”‚   โ”œโ”€โ”€ leave_manager.py      # LeaveManager โ€” leave balance & history
โ”‚   โ”œโ”€โ”€ ticket_manager.py     # TicketManager โ€” IT/equipment tickets
โ”‚   โ””โ”€โ”€ schemas.py            # Pydantic models for all entities
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ .python-version
โ”œโ”€โ”€ .gitignore
โ””โ”€โ”€ .env                   # ๐Ÿ”’ local secrets โ€” never committed

๐Ÿ“Œ Note: server.py does from HRMS import *, so the manager classes (employee_manager.py, meeting_manager.py, etc.) and schemas.py should live inside an HRMS/ package folder alongside __init__.py.


๐Ÿ› ๏ธ Requirements

  • ๐Ÿ Python 3.10+

  • Dependencies (see pyproject.toml):

    • fastmcp>=3.4.5

    • mcp[cli]>=1.9.4

    • pydantic>=2.13.4

    • python-dotenv


โš™๏ธ Setup

1. Clone & install

git clone https://github.com/Vraj-Data-Scientist/hr-onboarding-agent-with-MCP.git
cd hr-onboarding-agent-with-MCP

# using uv (recommended)
uv sync

# or using pip
pip install -e .

2. Configure environment variables

Create a .env file in the project root (already git-ignored ๐Ÿ”’):

EMAIL=your-smtp-email@gmail.com
EMAIL_PWD=your-app-specific-password

โš ๏ธ Security note: Use a Gmail App Password, not your real account password, and never commit .env to version control. If real credentials were ever pushed to a repo, rotate/revoke them immediately.

3. Run the server standalone (optional, for testing)

python server.py

This starts the MCP server over stdio transport.


๐Ÿ”Œ Connecting to Claude as an MCP Client

This server speaks MCP over stdio, so it plugs directly into any MCP-compatible Claude client.

๐Ÿ–ฅ๏ธ Option A โ€” Claude Desktop

  1. Open your Claude Desktop config file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

  2. Add this server under mcpServers:

{
  "mcpServers": {
    "hr-onboarding-agent": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/hr-onboarding-agent-with-MCP",
        "mcp",
        "run",
        "server.py"
      ],
      "env": {
        "EMAIL": "your-smtp-email@gmail.com",
        "EMAIL_PWD": "your-app-specific-password"
      }
    }
  }
}
  1. Restart Claude Desktop. A ๐Ÿ”จ tools icon should appear, showing the hr-assist server connected with tools like add_employee, send_email, create_ticket, schedule_meeting, and more.

  2. Prompt Claude naturally, e.g.:

    "Onboard a new employee named Priya Nair reporting to Tony Sharma."

๐Ÿ’ก Using the built-in onboarding prompt

The server exposes a ready-made MCP prompt, onboard_new_employee, which Claude Desktop (via the / prompt picker) and Claude Code can surface directly โ€” just supply employee_name and manager_name, and the full onboarding flow runs end-to-end.


๐Ÿงช Example

Prompt:

Onboard a new employee with the following details:
- Name: Vraj Dobariya
- Manager Name: Tony Sharma

What happens automatically:

  1. ๐Ÿ‘ค Employee added to HRMS with correct manager mapping

  2. ๐Ÿ“ง Welcome email sent with generated login

  3. ๐Ÿ“จ Manager notified of the new hire

  4. ๐ŸŽซ Tickets raised for laptop, ID card, and other equipment

  5. ๐Ÿ“… Introductory meeting scheduled between employee and manager


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.8/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: employee, leave, ticket, meeting, and email operations are separated. However, send_email has no description and could be confused with other notification-style actions, and get_employee_leave_balance vs get_leave_history require careful reading to distinguish.

    Naming Consistency4/5

    All names use snake_case with verb_noun structure, which is mostly predictable. Minor deviations exist, such as get_employee_details vs get_meetings, and some names include 'employee' while others rely on context.

    Tool Count5/5

    12 tools is a well-scoped set for an HR assistant, covering employees, leave, tickets, meetings, and email without feeling bloated or thin. Each tool appears to earn its place.

    Completeness3/5

    Core workflows are represented, but there are notable gaps: no list/update/delete employee operations, no leave cancellation or approval, and no ticket detail retrieval. These gaps could force agents to work around missing lifecycle operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers