HR Assistant Agent

HR Assistant Agent is an MCP-powered HR management system that automates onboarding, leave tracking, meeting scheduling, and IT ticketing through conversational AI. It unifies core HR tasks into a single, easy-to-use interface so you can accelerate workflows, reduce manual data entry, and deliver timely updates to employees and managers.

How to use

Interact with the HR Assistant Agent through an MCP client to perform common HR tasks via natural conversations. You can onboard new employees, check leave balances, schedule meetings, and raise IT tickets without navigating multiple systems. The agent orchestrates the steps behind the scenes, including updating employee records, sending welcome emails, notifying managers, provisioning equipment, and coordinating calendars.

How to install

Prerequisites you need before installation:

• Python 3.8 or higher
• Gmail account for email functionality (or another SMTP provider)
• Claude Desktop or API access for MCP client

Follow these concrete steps to set up and run the server locally with MCP support:

# Step 1: Clone the project
git clone https://github.com/yourusername/hr-assistant-agent.git
cd hr-assistant-agent

# Step 2: Install dependencies
# Using uv (recommended) if you have uv installed
uv pip install -r requirements.txt

# If you are using plain pip
pip install fastmcp pydantic python-dotenv

# Step 3: Configure environment variables
# Create a .env file in the project root with the following values
SENDER_EMAIL=your-email@gmail.com
SENDER_EMAIL_PWD=your-app-password

# Step 4: Run the server standalone for testing
python server.py

# Step 5: Connect via MCP client (e.g., Claude Desktop) by configuring the MCP server entry

Configuration to connect via MCP client

{
  "mcpServers": {
    "hr_assistant": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "SENDER_EMAIL": "your-email@gmail.com",
        "SENDER_EMAIL_PWD": "your-app-password"
      }
    }
  }
}

Additional setup notes

Step 4 in the CLI-based setup mirrors the configuration you provide in the MCP client. Ensure the absolute path to server.py is correct on your machine. Restart the MCP client after adding the hr_assistant entry to establish the connection.

Security and credentials

Store credentials securely in a .env file and do not commit this file to version control. Use app-specific passwords for Gmail and enable TLS for email communications. Consider adding authentication and audit logging for production deployments.

Troubleshooting

If the MCP connection does not appear in your client, verify the path to server.py and ensure Python is accessible from your environment. Check that the .env variables are loaded and that the server runs without errors in standalone mode before reattempting the MCP connection.

Seeded test data and tools

The system ships with sample data including an organizational structure, sample leaves, meetings, and IT tickets to help you experiment with the workflows.

Notes on usage examples

Examples of typical interactions include onboarding a new employee, checking leave balances, scheduling meetings, and creating IT tickets. The agent provides confirmations for each step, such as updating employee records, sending emails, notifying managers, provisioning devices, and scheduling introductory meetings.

Seeded test data

The sample organization includes leadership, engineering, and product teams, plus a set of eight employees with varying leave balances and scheduled meetings to illustrate real-world usage.

Available tools

add_employee

Create a new employee record and assign to a manager, updating the organizational structure accordingly.

get_employee

Retrieve details for a specific employee by ID or name, including hierarchical position and contact information.

search_employee_by_name

Fuzzy search to locate employees by partial or similar names when exact matches are not found.

leave_balance

Check an individual’s leave balance and view recent leave history.

apply_leave

Submit a leave request and update balances upon approval or denial.

schedule_meeting

Create a meeting entry, assign participants, and detect scheduling conflicts.

cancel_meeting

Cancel an existing meeting and notify participants.

create_ticket

Open an IT equipment or service ticket, track its status, and update stakeholders.

update_ticket

Modify an existing IT ticket with new details or status changes.

send_email

Automate email notifications for onboarding, approvals, and updates.