HR Management System (MCP Server)

⚠️ Work in progress. This project is still under active development and is not production-ready. The manager functions in HRMS/ are mock implementations that mimic the API calls of Keka HR software, using in-memory sample data instead of real Keka API integration.

An HR assistant exposed as an MCP (Model Context Protocol) server. It lets an MCP-compatible client (e.g. Claude Desktop) manage employees, tickets, leaves, and meetings, and send emails — backed by in-memory data that is seeded with sample employees on startup.

Features

The MCP server (server.py) exposes the following tools and prompt:

Tool	Description
add_employee	Add a new employee to the HRMS.
get_employee_details	Look up an employee's details by name.
create_ticket	Raise a ticket for equipment/items (laptop, ID card, etc.).
update_ticket_status	Update a ticket's status.
list_tickets	List tickets for an employee, optionally filtered by status.
send_email	Send an email via SMTP.

Prompt	Description
onboard_new_employee	Guided workflow to onboard a new hire end-to-end.

Additional domain logic lives in the HRMS/ package (employee, leave, meeting, and ticket managers plus Pydantic schemas.py). These managers currently mock Keka's HR API; sample data is loaded by utils.seed_services on server start.

Requirements

• Python >= 3.12
• uv (recommended) for dependency management

Setup

1. Clone the repository:

   git clone <your-repo-url>
   cd HR_Management_System
   

2. Install dependencies:

   uv sync
   

3. Configure environment variables. Copy the example file and fill in your SMTP credentials:

   cp .env.example .env
   

   Variable	Description
   MS_EMAIL	Sender email address / SMTP login.
   MS_EMAIL_PWD	SMTP password or app password.

   For Gmail, generate an App Password rather than using your account password.

Running

Start the MCP server (uses stdio transport):

uv run server.py

To use it with an MCP client such as Claude Desktop, add an entry to the client's MCP server configuration pointing at this command, for example:

{
  "mcpServers": {
    "atliq-hr-assist": {
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "/absolute/path/to/HR_Management_System"
    }
  }
}

You can also test the email sender directly:

uv run emails.py

Project structure

.
├── server.py          # MCP server entry point (tools & prompts)
├── emails.py          # SMTP email sender
├── utils.py           # Seeds the managers with sample data
├── main.py            # Hello-world placeholder
├── HRMS/              # Core domain package (mocks Keka HR API)
│   ├── employee_manager.py
│   ├── leave_manager.py
│   ├── meeting_manager.py
│   ├── ticket_manager.py
│   └── schemas.py     # Pydantic models
├── .env.example       # Template for required environment variables
└── pyproject.toml

Roadmap / TODO

• Replace the mock HRMS/ managers with real Keka HR API integration.
• Persist data instead of using in-memory seeded sample data.
• Expand MCP tool coverage for leave and meeting management.

Notes

• Data is stored in memory and re-seeded on every start; it is not persisted.
• Never commit your .env file — it contains secrets and is git-ignored.