🤖 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	✅

---

🏗️ 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

• 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_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

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
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.

---

<p align="center">Built with 🧠 by <a href="https://github.com/saibalajijammu">Saibalaji Jammu</a></p>