Labsco
mz462 logo

Paylocity

from mz462

A server to fetch data from Paylocity API endpoints.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#social-media#git#security

mcpPaylocity MCP Server

smithery badge

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

Components

Resources

The server implements Paylocity API resources with:

  • Custom paylocity:// 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

Tools

The server implements the following tools:

  • fetch_employees - Fetches all employees for a company
    • Takes optional company_id parameter
  • fetch_employee_details - Fetches details for a specific employee
    • Takes required employee_id and optional company_id parameters
  • fetch_employee_earnings - Fetches earnings data for a specific employee
    • Takes required employee_id and optional company_id parameters
  • fetch_company_codes - Fetches company codes for a specific resource
    • Takes required code_resource and optional company_id parameters
  • fetch_employee_local_taxes - Fetches local taxes for a specific employee
    • Takes required employee_id and optional company_id parameters
  • fetch_employee_paystatement_details - Fetches pay statement details for a specific date
    • Takes required employee_id, year, check_date and optional company_id parameters

Future Implementations

The following endpoints will be implemented in future updates:

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

Security

⚠️ IMPORTANT: This application caches authentication tokens in the src/mcppaylocity/access_token/ directory. These files contain sensitive credentials and should never be 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:

  1. Remove the files from the repository: git rm --cached src/mcppaylocity/access_token/token.json src/mcppaylocity/access_token/token_info.txt
  2. Commit the removal: git commit -m "Remove accidentally committed token files"
  3. Consider rotating your Paylocity API credentials as they may have been compromised

Development

Building and Publishing

To prepare the package for distribution:

  1. Sync dependencies and update lockfile:
uv sync
  1. Build package distributions:
uv build

This will create source and wheel distributions in the dist/ directory.

  1. Publish to PyPI:
uv publish

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

  • Token: --token or UV_PUBLISH_TOKEN
  • Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

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

You can launch the MCP Inspector via npm with this command:

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

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Architecture

The server is built with the following components:

  1. PaylocityClient - Handles communication with the Paylocity API
  2. TokenManager - Manages authentication tokens, including caching and renewal
  3. FastMCP Server - Exposes Paylocity data through MCP resources and tools