HRMS Tool

Overview

HRMS Tool is a Model Context Protocol server that turns a set of core HR workflows — onboarding, offboarding, leave tracking, meeting scheduling, IT ticketing, and email — into tools an AI agent can call directly.

Instead of clicking through an HR portal, you can ask an MCP-connected assistant things like:

"Onboard Marcus Webb as a new report under Elena Cross, starting Monday." "Who on Naomi Steele's team is running low on leave?" "Close out all of Diego Ramos's open tickets and cancel his upcoming meetings — he's leaving Friday."

The assistant plans the steps, calls the right tools in the right order, and reports back — using the guided prompts below for multi-step workflows, or individual tools for one-off actions.

Related MCP server: HRizzle-HR-Assist

✨ Features

• 👤 Employee management — add, update, look up, and search employees; resolve manager/report relationships

• 🌴 Leave management — check balances, apply for leave, review history

• 📅 Meeting scheduling — book, list, and cancel meetings with conflict detection

• 🎫 Ticket system — raise equipment/resource requests, track status, filter and inspect tickets

• 📧 Email — send transactional email via Gmail SMTP (plain text, HTML, and attachments)

• 🧭 Guided prompts — pre-built, multi-tool workflows for onboarding, offboarding, and team leave reporting

• 🌱 Seeded demo data — spins up with a realistic org chart, leave history, meetings, and tickets so you can try it immediately

🏗️ Architecture

flowchart LR
    Client(["MCP Client<br/>(Claude Desktop, etc.)"])

    subgraph MCPServer["mcp-server/"]
        Server["server.py<br/>MCPServer('HRMS Tool')"]
    end

    subgraph HRMSPkg["hrms/"]
        EM["EmployeeManager"]
        LM["LeaveManager"]
        MM["MeetingManager"]
        TM["TicketManager"]
        MAIL["EmailManager"]
    end

    subgraph UtilsPkg["utils/"]
        Seed["seed_services()"]
    end

    Client <-->|stdio| Server

    Server --> EM
    Server --> LM
    Server --> MM
    Server --> TM
    Server --> MAIL
    Server -->|once, at startup| Seed

    EM -->|holds a reference to| LM
    Seed --> EM
    Seed --> LM
    Seed --> MM
    Seed --> TM

    MAIL -->|SMTP| Gmail[(Gmail)]

hrms/schemas.py isn't drawn separately above — it's the Pydantic model layer that every manager and every tool signature depends on.

All data lives in memory for the lifetime of the process — there's no database. Every restart re-seeds a fresh, randomized dataset (see Data & Persistence below).

📁 Project Structure

hrms-claude-tool/
├── hrms/
│   ├── email_manager.py      # Gmail SMTP sender
│   ├── employee_manager.py   # employee CRUD, org chart, name search
│   ├── leave_manager.py      # leave balances & history
│   ├── meeting_manager.py    # meeting scheduling & cancellation
│   ├── schemas.py            # Pydantic models (Employee, Leave, Meeting, Ticket, Email)
│   └── ticket_manager.py     # ticket lifecycle
├── mcp-server/
│   └── server.py             # MCP server entrypoint: tools + prompts
├── utils/
│   └── utils.py              # seed_services() — dummy data generator
├── .env                       # Gmail credentials (not committed)
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── uv.lock

⚙️ Prerequisites

• Python 3.14+

• uv for dependency management (recommended)

• A Gmail account with an App Password, if you want the email tool to work (2-Step Verification must be enabled first)

🚀 Installation

# Clone the repo
git clone <your-repo-url>
cd hrms-claude-tool

# Install dependencies
uv sync

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]>=2.0.0" "pydantic>=2.13.4" "requests>=2.34.2" python-dotenv

Note: email_manager.py imports python-dotenv to load .env, but it isn't currently listed in pyproject.toml's dependencies — add it there too if you're using uv sync.

🔐 Environment Variables

Email sending needs Gmail SMTP credentials. Populate the .env file in the project root with:

GMAIL_SENDER_EMAIL=your-address@gmail.com
GMAIL_APP_PASSWORD=your-16-character-app-password

Generate an App Password at myaccount.google.com/apppasswords (Security → 2-Step Verification → App passwords). A regular Gmail password will not work.

▶️ Running the Server

uv run mcp-server/server.py

This starts the MCP server over stdio and seeds it with demo employees, leave records, meetings, and tickets.

Connecting from Claude Desktop / Claude Code

Add an entry to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "hrms-tool": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/hrms-claude-tool", "run", "mcp-server/server.py"]
    }
  }
}

Restart the client, and the tools and prompts below become available in conversation.

🛠️ Available Tools

Employee & Org Chart

Leave

Meetings

Tickets

Email

🧭 Available Prompts

Prompts chain multiple tools into a complete workflow — hand one a name and let the agent drive.

💾 Data & Persistence

• All data is held in memory — nothing survives a server restart.

• On every startup, seed_services() generates a coherent demo dataset: an 8-person org chart across two teams, randomized leave balances/history, 2–6 upcoming meetings per employee, and 8–15 tickets in mixed states.

• Employee IDs follow E001, E002, …; ticket IDs follow T0001, T0002, …

• New employees default to a 20-day leave balance unless seeded otherwise.

If you need data to persist across restarts, you'll want to swap the in-memory dicts/lists in each manager class for a real datastore.

⚠️ Known Limitations

• No authentication or authorization on tool calls — access control is left entirely to the MCP client.

• No persistence layer (see above).

• Email sending is Gmail-only, via SMTP + App Password.

• Meeting conflict detection only checks for an exact timestamp match, not overlapping ranges.

📄 License

This project is licensed under the MIT License.