Paylocity

A Model Context Protocol (MCP) server to fetch data from Paylocity API endpoints.

The server implements Paylocity API resources with:

- Custompaylocity://URI scheme for accessing Paylocity data
- The following resources are available:

- paylocity://employees/{company_id}- List all employees for a company
- paylocity://employees/{company_id}/{employee_id}- Get details for a specific employee
- paylocity://earnings/{company_id}/{employee_id}- Get earnings data for a specific employee
- paylocity://codes/{company_id}/{code_resource}- Get company codes for a specific resource
- paylocity://localtaxes/{company_id}/{employee_id}- Get local taxes for a specific employee
- paylocity://paystatement/{company_id}/{employee_id}/{year}/{check_date}- Get pay statement details for a specific date

The server implements the following tools:

- fetch_employees- Fetches all employees for a company

- Takes optionalcompany_idparameter

- Takes requiredemployee_idand optionalcompany_idparameters

- Takes requiredemployee_idand optionalcompany_idparameters

- Takes requiredcode_resourceand optionalcompany_idparameters

- Takes requiredemployee_idand optionalcompany_idparameters

- Takes requiredemployee_id,year,check_dateand optionalcompany_idparameters

The following endpoints will be implemented in future updates:

- Higher level insights (e.g. turnover rate, headcount by department, rate comparison etc.)

The server requires the following environment variables to be set:

- PAYLOCITY_CLIENT_ID- Your Paylocity API client ID
- PAYLOCITY_CLIENT_SECRET- Your Paylocity API client secret
- PAYLOCITY_COMPANY_IDS- Comma-separated list of company IDs to use
- PAYLOCITY_ENVIRONMENT- API environment to use (productionortesting)
- MODEL_COST_PRIORITY- Optional cost priority for model selection
- MODEL_SPEED_PRIORITY- Optional speed priority for model selection
- MODEL_INTELLIGENCE_PRIORITY- Optional intelligence priority for model selection
- MODEL_HINTS- Optional comma-separated model name hints

These can be set in a.envfile in the project root directory.

On startup the server responds to the MCPinitializerequest with handshake data containing its capabilities, instructions, protocol version and server info. The instructions field describes how to use the Paylocity resources and tools.

⚠️IMPORTANT: This application caches authentication tokens in thesrc/mcppaylocity/access_token/directory. These files contain sensitive credentials and shouldneverbe committed to version control.

The repository includes these paths in.gitignore, but please verify that token files are not accidentally committed when pushing changes.

If you've accidentally committed token files, follow these steps:
- Remove the files from the repository:git rm --cached src/mcppaylocity/access_token/token.json src/mcppaylocity/access_token/token_info.txt
- Commit the removal:git commit -m "Remove accidentally committed token files"
- Consider rotating your Paylocity API credentials as they may have been compromised

On MacOS:~/Library/Application\ Support/Claude/claude_desktop_config.jsonOn Windows:%APPDATA%/Claude/claude_desktop_config.json

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

"mcpServers": { "mcpPaylocity": { "command": "uvx", "args": [ "mcppaylocity" ] } }

To prepare the package for distribution:

This will create source and wheel distributions in thedist/directory.

Note: You'll need to set PyPI credentials via environment variables or command flags:

- Token:--tokenorUV_PUBLISH_TOKEN
- Or username/password:--username/UV_PUBLISH_USERNAMEand--password/UV_PUBLISH_PASSWORD

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using theMCP Inspector.

You can launch the MCP Inspector vianpmwith this command:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcpPaylocity run mcppaylocity

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar