# Paylocity MCP Server

An MCP (Model Context Protocol) server that connects Claude Desktop to the Paylocity API. Sensitive data like SSNs and bank account numbers are automatically redacted before reaching Claude.

## Setup

### 1. Install

```bash
git clone <this-repo>
cd payolocity-mcp
npm install
npm run build
```

### 2. Get your Paylocity API credentials

You'll need two sets of API keys from your Paylocity admin:

- **WebLink API Key** (Client ID + Client Secret) — used for employee details, pay statements, and write operations
- **NextGen API Key** (Client ID + Client Secret) — used for the employee directory search

Both come as password-protected zip files from Paylocity. Ask your Paylocity admin or implementation contact for access.

You'll also need your **Company ID** — the numeric ID Paylocity assigned to your company (e.g. `348353`).

### 3. Configure Claude Desktop

Open your Claude Desktop config file:

- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add the `paylocity` server to `mcpServers`:

```json
{
  "mcpServers": {
    "paylocity": {
      "command": "node",
      "args": ["/full/path/to/payolocity-mcp/dist/server.js"],
      "env": {
        "PAYLOCITY_CLIENT_ID": "your-weblink-client-id",
        "PAYLOCITY_CLIENT_SECRET": "your-weblink-client-secret",
        "PAYLOCITY_ENV": "production",
        "PAYLOCITY_COMPANY_ID": "your-company-id",
        "PAYLOCITY_NEXTGEN_CLIENT_ID": "your-nextgen-client-id",
        "PAYLOCITY_NEXTGEN_CLIENT_SECRET": "your-nextgen-client-secret"
      }
    }
  }
}
```

Replace the placeholder values with your actual credentials and the full path to where you cloned the repo.

### 4. Restart Claude Desktop

Quit and reopen Claude Desktop. The Paylocity tools will appear automatically.

## What you can do

Once connected, you can ask Claude things like:

- "Find Sean Canton in Paylocity"
- "What's Jeremy Allen's job title and department?"
- "Show me the company headcount by department"
- "Pull pay statements for employee 76 for 2025"
- "What are the direct deposit accounts for employee 1?"

## Available tools

| Tool | Description |
|------|-------------|
| **search_employees** | Find employees by name, title, email, or ID |
| **get_employee** | Full employee detail (pay, benefits, tax, addresses, contacts) |
| **get_pay_statements** | Pay history with summary and line-item details |
| **get_direct_deposit** | Bank account info (numbers redacted) |
| **get_company_summary** | Headcount and department breakdown |
| **update_employee** | Change address, title, department, pay rate, status |
| **add_earnings** | Add a bonus, commission, or other one-time pay |
| **add_employee** | Create a new employee record (skips onboarding workflow) |
| **add_onboarding_employee** | Start a new hire through the self-service onboarding workflow |
| **get_employee_custom_fields** | Pull custom profile fields (t-shirt size, etc.) added during onboarding |
| **get_tshirt_size** | Shortcut: pull just the t-shirt size for swag/uniform requests |

## Not yet supported

These were requested but aren't (currently) reachable via Paylocity's public Open API:

| Capability | Status | Notes |
|------------|--------|-------|
| **Documents library** | Separate API | Paylocity exposes documents through a distinct "Document Partner API" with its own credentials. Needs separate WebLink key with document scopes; not part of the v2 surface we use here. |
| **Onboarding events / workflow steps** | Limited | We can *start* onboarding (above), but creating arbitrary events on an in-flight workflow isn't exposed. |
| **Performance reviews** | Not in public API | The Performance module's review scores are not exposed via the Open API. Available only through Paylocity's UI exports / Data Exchange reports. |
| **Surveys** | Not in public API | Survey build and response data isn't a public API resource. Same path as Performance — UI / Data Exchange only. |

If your Paylocity contract includes Data Exchange (scheduled report exports to S3/SFTP), pulling Performance and Survey data is doable that way — but it lives outside this MCP server.

## Data protection

All API responses are scrubbed before reaching Claude:

- **SSNs** show only the last 4 digits (`***-**-1234`)
- **Bank account numbers** are masked
- **Routing numbers** are fully redacted
- **Company FEIN** is masked

This happens at the server level — Claude never sees the raw data.

## Credentials

- WebLink API secrets expire after 365 days
- NextGen API secrets expire after 365 days
- Check the expiration dates in the zip file names from Paylocity