HRMS Tool

Übersicht

HRMS Tool ist ein Model Context Protocol-Server, der eine Reihe von Kern-HR-Workflows – Onboarding, Offboarding, Urlaubsverfolgung, Besprechungsplanung, IT-Ticketing und E-Mail – in Werkzeuge verwandelt, die ein KI-Agent direkt aufrufen kann.

Anstatt durch ein HR-Portal zu klicken, können Sie einen MCP-verbundenen Assistenten Dinge fragen wie:

„Binden Sie Marcus Webb als neuen Mitarbeiter unter Elena Cross ein, ab Montag.“ „Wem in Naomi Steeles Team geht der Urlaub aus?“ „Schließen Sie alle offenen Tickets von Diego Ramos und stornieren Sie seine anstehenden Besprechungen – er geht am Freitag.“

Der Assistent plant die Schritte, ruft die richtigen Werkzeuge in der richtigen Reihenfolge auf und berichtet zurück – unter Verwendung der unten stehenden geführten Prompts für mehrschrittige Workflows oder einzelner Tools für einmalige Aktionen.

Related MCP server: HRizzle-HR-Assist

✨ Funktionen

• 👤 Mitarbeiterverwaltung – Mitarbeiter hinzufügen, aktualisieren, nachschlagen und suchen; Vorgesetzten-/Berichtsbeziehungen auflösen

• 🌴 Urlaubsverwaltung – Guthaben prüfen, Urlaub beantragen, Verlauf einsehen

• 📅 Besprechungsplanung – Besprechungen mit Konflikterkennung buchen, auflisten und stornieren

• 🎫 Ticketsystem – Ausrüstungs-/Ressourcenanfragen erstellen, Status verfolgen, Tickets filtern und prüfen

• 📧 E-Mail – Transaktions-E-Mails über Gmail SMTP senden (Klartext, HTML und Anhänge)

• 🧭 Geführte Prompts – vorgefertigte Multi-Tool-Workflows für Onboarding, Offboarding und Team-Urlaubsberichte

• 🌱 Seed-Demodaten – Startet mit einer realistischen Organigramm, Urlaubsverlauf, Besprechungen und Tickets, sodass Sie es sofort ausprobieren können

🏗️ Architektur

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 ist oben nicht separat eingezeichnet – es ist die Pydantic-Modellschicht, von der jeder Manager und jede Tool-Signatur abhängt.

Alle Daten befinden sich im Arbeitsspeicher für die Lebensdauer des Prozesses – es gibt keine Datenbank. Jeder Neustart erzeugt einen neuen, zufälligen Datensatz (siehe Daten & Persistenz unten).

📁 Projektstruktur

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

⚙️ Voraussetzungen

• Python 3.14+

• uv für die Abhängigkeitsverwaltung (empfohlen)

• Ein Gmail-Konto mit einem App-Passwort, wenn das E-Mail-Tool funktionieren soll (Zwei-Faktor-Authentifizierung muss zuerst aktiviert sein)

🚀 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

Hinweis: email_manager.py importiert python-dotenv, um .env zu laden, aber es ist derzeit nicht in den Abhängigkeiten von pyproject.toml aufgeführt – fügen Sie es auch dort hinzu, wenn Sie uv sync verwenden.

🔐 Umgebungsvariablen

Zum Senden von E-Mails werden Gmail-SMTP-Anmeldedaten benötigt. Füllen Sie die .env-Datei im Projektstammverzeichnis mit:

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

Generieren Sie ein App-Passwort unter myaccount.google.com/apppasswords (Sicherheit → Zwei-Faktor-Authentifizierung → App-Passwörter). Ein normales Gmail-Passwort funktioniert nicht.

▶️ Server ausführen

uv run mcp-server/server.py

Dies startet den MCP-Server über stdio und befüllt ihn mit Demo-Mitarbeitern, Urlaubsdatensätzen, Besprechungen und Tickets.

Verbindung von Claude Desktop / Claude Code

Fügen Sie einen Eintrag zu Ihrer MCP-Client-Konfiguration hinzu (z. B. claude_desktop_config.json):

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

Starten Sie den Client neu, und die unten stehenden Tools und Prompts werden im Gespräch verfügbar.

🛠️ Verfügbare Tools

Mitarbeiter & Organigramm

Urlaub

Besprechungen

Tickets

E-Mail

🧭 Verfügbare Prompts

Prompts verketten mehrere Tools zu einem vollständigen Workflow – übergeben Sie einen Namen und lassen Sie den Agenten die Arbeit machen.

💾 Daten & Persistenz

• Alle Daten werden im Arbeitsspeicher gehalten – nichts überlebt einen Serverneustart.

• Bei jedem Start generiert seed_services() einen kohärenten Demo-Datensatz: ein 8-Personen-Organigramm über zwei Teams, zufällige Urlaubsguthaben/-verläufe, 2–6 anstehende Besprechungen pro Mitarbeiter und 8–15 Tickets in gemischten Zuständen.

• Mitarbeiter-IDs folgen E001, E002, …; Ticket-IDs folgen T0001, T0002, …

• Neue Mitarbeiter haben standardmäßig ein Urlaubsguthaben von 20 Tagen, sofern nicht anders gesät.

Wenn Daten über Neustarts hinweg erhalten bleiben sollen, müssen Sie die In-Memory-Dicts/Listen in jeder Manager-Klasse durch einen echten Datenspeicher ersetzen.

⚠️ Bekannte Einschränkungen

• Keine Authentifizierung oder Autorisierung bei Tool-Aufrufen – die Zugriffskontrolle wird vollständig dem MCP-Client überlassen.

• Keine Persistenzschicht (siehe oben).

• E-Mail-Versand ist nur über Gmail per SMTP + App-Passwort möglich.

• Die Besprechungskonflikterkennung prüft nur auf eine exakte Zeitstempelübereinstimmung, nicht auf überlappende Zeiträume.

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.