HRIS MCP Connector

A Model Context Protocol (MCP) server that gives an AI client like Claude Desktop read-only access to HR information system data through a typed tool layer. Built with the official Python MCP SDK.

This public repository is a reference implementation backed by a synthetic mock data layer. The production version swaps that layer for authenticated calls to a real HRIS such as Rippling, leaving the tool surface identical. No real employee data, no credentials, and no vendor-specific configuration are included here.

What It Does

It exposes four read-only tools to an MCP client:

Tool	What it returns
list_recent_hires	Employees who started within the last N days, newest first
get_employee	A single employee record by ID
list_departments	Each department with its current headcount
get_pto_balance	Remaining paid-time-off hours for one employee

Ask Claude something like "who joined in the last two weeks?" and it calls list_recent_hires and answers from the result.

Why It's Built This Way

Read-only by design. Every tool retrieves information; none changes HR data. Write actions belong behind authentication, authorization, audit logging, and human approval, which are deliberately out of scope for a public reference server.

A clean tool surface over a swappable data layer. The MCP tools call plain functions in mock_data.py. In production, that one module is replaced with real HRIS API calls and nothing else changes. That separation is the whole point: the AI client sees a stable contract regardless of what's behind it.

Testable without a server. Because the query logic lives in plain functions, the test suite checks it directly with a fixed reference date. No process, no network, no flakiness. See tests/.

Protocol-safe logging. This is a stdio server, so stdout carries the protocol. All diagnostics go to stderr, which keeps the message stream clean.

Architecture

flowchart LR
    C[Claude / MCP Client] --> S[MCP Server: tools]
    S --> D[Data Layer]
    D --> M[Mock Data]
    D -. production .-> API[Real HRIS API]

Setup

1. pip install -r requirements.txt
2. Run the server: python src/server.py

Connect it to Claude Desktop

Add this to your Claude Desktop config file, using the absolute path to this repo:

{
  "mcpServers": {
    "hris-connector": {
      "command": "python",
      "args": ["/absolute/path/to/hris-mcp-connector/src/server.py"]
    }
  }
}

Restart Claude Desktop fully (quit, don't just close the window). The four tools then appear in the client.

Going to Production

To connect a real HRIS, replace the functions in src/mock_data.py with authenticated API calls. The API token goes in a .env file (see .env.example), which is gitignored and never committed. The tool definitions in src/server.py stay exactly as they are.

Status

Reference implementation with a mock data layer. A production version of this connector runs against a live HRIS in a real HR environment; this public repository contains the pattern and the mock layer only.