Paylocity

🚀 MCP Paylocity Server

A Model Context Protocol (MCP) server for retrieving data from Paylocity API endpoints.

🚀 Quick Start

Installation and Configuration

Run the following commands in the terminal to install and start the server:

cd /path/to/mcpPaylocity
npm install
npm start

Claude Desktop Configuration

Choose the following configuration methods based on the environment:

Development Environment Configuration

{
  "development": {
    "command": "uv --directory . run mcppaylocity",
    "args": []
  }
}

Production Environment Configuration

{
  "production": {
    "command": "uv --directory . run mcppaylocity",
    "args": []
  }
}

✨ Features

Resource Access

• Custom URI Scheme: Use the paylocity:// custom URI scheme to access Paylocity data through the following paths:
  • /employees: Retrieve employee information.
  • /departments: Retrieve department information.
  • /jobs: Retrieve job information.
  • /salary-slips: Retrieve salary slip information.

Tool Implementation

• Data Retrieval Tools:

  • fetch_employees: Retrieve a list of employees based on filtering criteria (e.g., department, position).
  • fetch_departments: Retrieve information about all departments.
  • fetch_jobs: Retrieve information about all jobs.
  • fetch_salary_slips: Retrieve detailed salary slip information based on the employee ID.

• Future Plans:

  • Add advanced features such as performance data, attendance records, etc. Currently under development.

📦 Installation

Environment Variable Configuration

To ensure the server runs properly, set the following environment variables and store them in the .env file:

Notes

• Sensitive Information Management: Authentication tokens are cached in a local file. Ensure the security of the server's operating environment.
• Version Control Tip: Do not commit the .env file containing sensitive information to the code repository.

📚 Documentation

Building and Publishing

1. Build:

npm run build

2. Package:

npm run package

3. Publish:

npm run publish

• Make sure to set up your npm user token or use environment variables for authentication.

Debugging Tips

Since the MCP server runs through standard input and output, debugging can be challenging. It is recommended to use the MCP Inspector for debugging:

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

After running, the inspector will display the browser access address to assist you with debugging.

Architecture Explanation

Component Structure

1. PaylocityClient: Responsible for communicating with the Paylocity API.
2. TokenManager: Manages the caching and automatic refresh of authentication tokens.
3. FastMCP Server: Exposes Paylocity data through MCP resources and tools.

🔧 Technical Details

Security Warnings

Since the server caches authentication tokens, the following operations must be strictly prevented:

1. Do not commit the .env file to the version control system.
2. If accidentally committed, take immediate measures:
   • Delete the file from the remote repository.
   • Modify the commit history to remove the file.
   • Update the local environment and redeploy.

📄 License

MIT License

Copyright (c) 2024 MJ Zou (@mjzou)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

• Copyright Notice: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
• Limitation of Liability: The copyright holders shall not be liable for any damages arising from the use or inability to use the Software, including but not limited to direct, indirect, incidental, special, exemplary, or consequential damages.