# HR Assistant MCP Server

A practical local HR assistant for employee onboarding, leave tracking, meeting coordination, and workplace requests. It connects to any MCP-compatible client and runs without a database or paid service.

## System design

![Hand-drawn HR Assistant system design](assets/hr-assistant-system-design.png)

The MCP server is the single entry point for HR workflows. Employee, leave, meeting, and request features are separate modules, while email delivery stays optional. Data is stored locally in memory for a fast demo experience.

## Highlights

- Onboard employees with a single tool call.
- Maintain an employee directory with manager and direct-report relationships.
- Check leave balances, submit leave dates, and review leave history.
- Schedule, list, and cancel orientation or HR meetings.
- Create and update laptop, headset, access-badge, and other workplace requests.
- Send notifications through SMTP when credentials are configured locally.
- Start with deterministic sample employees for immediate testing.

## Getting started

Requirements: Python 3.10 or later.

```powershell
git clone https://github.com/sarthak-here/hr-assistant-mcp.git
cd hr-assistant-mcp
python -m pip install -e ".[test]"
python server.py
```

The server communicates through standard input/output, which is what MCP clients expect. It will not display an interactive chat prompt when launched directly.

Run the test suite whenever you make changes:

```powershell
python -m pytest
```

## Add to an MCP client

Use an absolute path to the cloned project in your client configuration.

```json
{
  "mcpServers": {
    "hr-assistant": {
      "command": "python",
      "args": ["C:\\path\\to\\hr-assistant-mcp\\server.py"]
    }
  }
}
```

After connecting, try one of these requests:

```text
Show the current employee directory.
Onboard Priya Shah as a Product Analyst reporting to EMP-002.
Check the leave balance for EMP-003.
Create a monitor request for EMP-004.
```

### Companion Python client

The public
[`hr-assistant-mcp-client`](https://github.com/sarthak-here/hr-assistant-mcp-client)
repository provides a working LangChain MCP client for this server. Keep both
repositories as sibling folders and the client resolves this server
automatically, or set `HR_ASSISTANT_MCP_DIR` when using a different layout.

```text
projects/
|-- hr-assistant-mcp-client/
`-- hr-assistant-mcp/
```

## Main tools

| Area | Tools |
| --- | --- |
| Employee directory | `create_employee`, `find_employees`, `get_employee`, `get_direct_reports` |
| Leave | `get_leave_balance`, `apply_leave`, `get_leave_history` |
| Meetings | `schedule_meeting`, `list_meetings`, `cancel_meeting` |
| Workplace requests | `create_equipment_request`, `update_request_status`, `list_requests` |
| Onboarding | `onboard_employee` |
| Notifications | `send_notification` |

`onboard_employee` creates the employee record, leave account, and the standard laptop, headset, and access-badge requests together. Schedule orientation separately once a time is confirmed.

## Email setup

Email is optional. Copy `.env.example` to `.env`, then fill in the SMTP values if you want to use `send_notification`.

```powershell
Copy-Item .env.example .env
```

The `.env` file is ignored by Git. All other HR features work without email configuration.

## Project files

```text
hr-assistant-mcp/
  assets/             Hand-drawn system-design image
  peopleops/          Domain models and HR workflow managers
  tests/              Automated checks
  server.py           MCP tools
  emails.py           Optional SMTP notifications
  .env.example        Safe configuration template
  pyproject.toml      Project dependencies and test settings
```