🧑‍💼 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

---

🗂️ 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"
      }
    }
  }
}

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

---