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

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.

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:

python -m pytest

Add to an MCP client

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

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

After connecting, try one of these requests:

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.

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.

Copy-Item .env.example .env

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

Project files

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