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
pip install -r requirements.txt- 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.
