Paylocity

Queries Paylocity data through MCP resources and tools for employees, earnings, codes, local taxes, and pay statements.

python

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mz462-mcppaylocity": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcpPaylocity",
        "run",
        "mcppaylocity"
      ],
      "env": {
        "MODEL_HINTS": "YOUR_HINTS",
        "MODEL_COST_PRIORITY": "high",
        "PAYLOCITY_CLIENT_ID": "YOUR_VALUE",
        "MODEL_SPEED_PRIORITY": "normal",
        "PAYLOCITY_COMPANY_IDS": "123,456",
        "PAYLOCITY_ENVIRONMENT": "production",
        "PAYLOCITY_CLIENT_SECRET": "YOUR_VALUE",
        "MODEL_INTELLIGENCE_PRIORITY": "high"
      }
    }
  }
}

This MCP server provides access to Paylocity data through a dedicated set of resources and tools. It lets you fetch employee lists, details, earnings, codes, local taxes, and pay statements using a lightweight MCP runtime. Use it to integrate Paylocity data into your MCP-enabled workflows and dashboards.

How to use

You interact with the Paylocity MCP server by running it locally and connecting an MCP client to its stdio interface. The server exposes a collection of resources you can query through MCP and a set of tools that fetch Paylocity data on demand. Use the client to request employee data, earnings, codes, taxes, and pay statements for specific company and employee combinations.

How to install

Prerequisites: you need a runtime capable of MCP stdio servers (the example uses UV-based tooling) and access to the Paylocity API credentials.

Install and run the Paylocity MCP server using the development configuration excerpt:

"mcpServers": {
  "mcpPaylocity": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/mcpPaylocity",
      "run",
      "mcppaylocity"
    ]
  }
}

Additional sections

Configuration and security details below help you run and protect the server in your environment.

Configuration

Environment variables you must provide for Paylocity access and model prioritization are described here. Set these in a .env file at the project root or export them in your shell before starting the server.

PAYLOCITY_CLIENT_ID=YOUR_VALUE
PAYLOCITY_CLIENT_SECRET=YOUR_VALUE
PAYLOCITY_ENVIRONMENT=production
PAYLOCITY_COMPANY_IDS=123,456
MODEL_COST_PRIORITY=high
MODEL_SPEED_PRIORITY=normal
MODEL_INTELLIGENCE_PRIORITY=high
MODEL_HINTS=YOUR_MODEL_HINTS

Security and maintenance

The server caches authentication tokens to optimize performance. Token files are stored under the src/mcppaylocity/access_token/ directory and must not be committed to version control. If you accidentally commit token files, remove them from the repository and rotate your API credentials.

If you need to rotate credentials, follow standard credential rotation practices and ensure you restart the server so it can obtain fresh tokens.

Troubleshooting

If you encounter issues starting the MCP server, enable debugging with the MCP Inspector tool. It provides a browser-based debugging view that helps you trace resource requests and tool invocations.

Available tools

fetch_employees

Fetches all employees for a company. Takes optional company_id.

fetch_employee_details

Fetches details for a specific employee. Requires employee_id and optional company_id.

fetch_employee_earnings

Fetches earnings data for a specific employee. Requires employee_id and optional company_id.

fetch_company_codes

Fetches company codes for a specific resource. Requires code_resource and optional company_id.

fetch_employee_local_taxes

Fetches local taxes for a specific employee. Requires employee_id and optional company_id.

fetch_employee_paystatement_details

Fetches pay statement details for a specific date. Requires employee_id, year, check_date and optional company_id.

Built by

VeilStrat

AI signals for GTM teams