UKG Ready MCP

MCP server for UKG Ready REST endpoints, including employees, timecards, exceptions, compensation, saved reports, and a generic authenticated endpoint tool.

Configuration

Copy .env.example to a local environment configuration and set:

• UKG_BASE_URL: UKG tenant base URL, defaulting to https://secure.entertimeonline.com.
• UKG_API_KEY, UKG_USERNAME, UKG_PASSWORD, UKG_COMPANY.
• UKG_DEFAULT_REPORT_ID: optional saved report ID.

Never commit real credentials or place them in source files.

Run

npm install
npm run build
npm start

The server communicates over MCP stdio. Available tools:

• get_ukg_saved_report_csv
• list_ukg_employees
• get_ukg_employee
• get_ukg_timecards
• list_ukg_exceptions
• get_ukg_compensation
• call_ukg_endpoint

The workforce tools use documented-style defaults and expose an optional path override because UKG Ready endpoint availability varies by tenant and enabled module. The generic tool accepts any API path, so credentials remain inside the server configuration. Add write tools only after the tenant's endpoint contract and permissions are confirmed.

UKG employee and Command Cloud driver mapping

The intended integration is that a UKG employee corresponds to a driver in Command Cloud. This mapping is a planned cross-system relationship, not an automatic assumption yet.

When implementing it, reconcile records using stable identifiers where available, then validate with supporting fields such as employee/driver name, employee number, phone, email, and active status. Keep an explicit mapping of the UKG employee ID to the Command Cloud driver ID; do not rely on names alone because names can change or be duplicated.

The mapping will support future workflows such as comparing UKG timecards or clock status with Command Cloud driver, dispatch, and ticket activity. The actual matching rules and source-of-truth decisions still need to be confirmed before writing synchronization tools.