Connect Clockify to ChatGPT: Track Time & Manage Project Workflows

If you need to connect Clockify to ChatGPT to automate time tracking, manage project lifecycles, or generate detailed financial reports, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calls and Clockify's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses Claude, check out our guide on connecting Clockify to Claude or explore our broader architectural overview on connecting Clockify to AI Agents.

Giving a Large Language Model (LLM) read and write access to a flexible time-tracking tool like Clockify is a massive engineering challenge. You have to handle complex relational data payloads, map dynamic custom fields to MCP tool definitions, and deal with strict workspace scoping across every endpoint. Every time a user changes a required custom field in Clockify, your custom server code must be updated, redeployed, and tested.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Clockify, connect it natively to ChatGPT, and execute complex workflows using natural language.

The Engineering Reality of the Clockify API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against Clockify's highly specific API is exceptionally painful.

If you decide to build a custom MCP server for Clockify, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Clockify:

Mandatory Workspace Scoping

Unlike APIs where a user context inherently maps to their data, nearly every action in Clockify requires a workspace_id. If an LLM needs to list projects, create an invoice, or log a time entry, it cannot just hit /time-entries. It must query /workspaces/{workspace_id}/time-entries. Your MCP server must guarantee the LLM retrieves, retains, and injects this ID into every subsequent tool call, or the requests will fail with generic 404s or 403s.

Required Custom Fields on Time Entries

Clockify allows workspace admins to mandate custom fields for time entries (e.g., requiring an "Issue Number" or "Billing Code"). If a workspace enforces this, standard time entry payloads will be rejected. Your MCP server must dynamically read the workspace's custom field schema and expose those requirements to the LLM. Hardcoding static JSON schemas for MCP tools fails completely in environments with dynamic custom data.

IETF Rate Limit Normalization and Handling

When dealing with automated agent workflows, LLMs can rapidly trigger API rate limits. Truto normalizes upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. However, Truto passes HTTP 429 errors directly to the caller - it does not automatically retry, throttle, or absorb rate limits. You are strictly responsible for implementing retry and exponential backoff logic on your client side when the Clockify API rejects excessive requests.

Generating a Clockify MCP Server

Truto automatically generates documentation-driven MCP tools from the underlying API schemas, flattening complex nested structures into clear, LLM-friendly descriptions. You can generate a Clockify MCP server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

If you are setting up a single connection or testing workflows, the UI is the fastest path.

1. Navigate to the integrated account page for your Clockify connection in the Truto dashboard.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (name, allowed methods, tags, and optional expiration).
5. Copy the generated MCP server URL. Treat this URL as a secure credential.

Method 2: Via the API

For production applications, you should generate MCP servers dynamically on behalf of your users. Make a POST request to /integrated-account/:id/mcp to create a scoped server endpoint.

curl -X POST https://api.truto.one/integrated-account/$INTEGRATED_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clockify Time Tracking for ChatGPT",
    "config": {
      "methods": ["read", "write"],
      "tags": ["time_entries", "projects", "workspaces"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a JSON object containing a url field (e.g., https://api.truto.one/mcp/<token>). This URL contains a hashed token that handles routing and authentication automatically.

Connecting the MCP Server to ChatGPT

Once you have your secure MCP URL, you need to register it with your ChatGPT environment. You can do this visually in the app or via configuration files.

Method 1: Via the ChatGPT UI

ChatGPT Pro, Plus, Enterprise, and Education tiers support custom connectors via Developer mode.

1. In ChatGPT, navigate to Settings -> Apps -> Advanced settings.
2. Enable the Developer mode toggle.
3. Under MCP servers / Custom connectors, click Add a new server.
4. Enter a name (e.g., "Clockify by Truto").
5. Paste the Truto MCP URL into the Server URL field.
6. Save the configuration. ChatGPT will immediately connect, handshake the JSON-RPC protocol, and discover the available Clockify tools.

Method 2: Via Manual Configuration File

If you are running local agents, Claude Desktop, or custom OpenAI orchestration, you can mount the MCP server using a standard configuration file, instructing the client to connect via Server-Sent Events (SSE).

{
  "mcpServers": {
    "clockify-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<your_secure_token>"
      ]
    }
  }
}

Clockify Hero Tools for AI Agents

Truto curates and transforms the Clockify REST API into highly reliable tools. By deriving these tools directly from the integration's schemas, AI agents receive explicitly mapped query and body parameters. Here are the highest-leverage tools available for Clockify.

list_all_clockify_workspaces

Because almost all Clockify operations require a workspace context, this tool is the mandatory first step for agent orientation. It returns all workspaces the authenticated user belongs to, allowing the agent to capture the id needed for subsequent calls.

"Find my Clockify workspaces and tell me their names and IDs."

list_all_clockify_workspace_projects

Lists all projects within a specific workspace, filterable by name, client, or active status. The agent uses this to map human-readable project names to system IDs before creating time entries or invoices.

"List all active projects in the 'Engineering' workspace."

create_a_clockify_workspace_time_entry

The core functionality of Clockify. This tool logs a new time entry. The LLM must pass the workspace_id, projectId, and start/end times. If the workspace enforces custom fields, the agent must include them in the customFields array.

"Log 2 hours of time today to the 'Website Redesign' project. The description is 'Frontend bug fixes'."

list_all_clockify_status_in_progreses

Returns all currently running (in-progress) time entries for the workspace. This is critical for agents acting as virtual assistants, allowing them to answer context-aware queries about current tasking.

"Am I currently tracking time on anything right now?"

create_a_clockify_workspace_invoice

Generates a new invoice inside a workspace. The LLM constructs a JSON body matching Clockify's schema, injecting workspace_id, clientId, currency, due date, and line items based on time tracked.

"Draft a new invoice in USD for Acme Corp based on the time I tracked this month. Make it due in 30 days."

create_a_clockify_reports_detailed

Generates a highly specific, detailed time entry report based on filter criteria. This tool is invaluable for agents auditing team performance, calculating contractor pay, or reconciling project budgets.

"Generate a detailed report of all time tracked by the frontend team last week."

To view the complete inventory of available operations, schema definitions, and parameters, visit the Clockify integration page.

Workflows in Action

Individual tools are useful, but MCP servers unlock their true power when LLMs chain them together to execute multi-step logic. Here is how ChatGPT orchestrates real-world Clockify workflows.

Scenario 1: Context-Aware Time Logging

Users rarely know the internal UUID of their projects. They just want to tell the agent what they worked on and have the system figure out the rest.

"Log 4 hours of work for the Acme Corp dashboard project. Describe it as 'Initial React setup'."

sequenceDiagram
    participant User as User
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP Server
    participant Clockify as "Clockify API"

    User->>ChatGPT: "Log 4 hours for the Acme Corp dashboard..."
    ChatGPT->>Truto: call list_all_clockify_workspaces
    Truto->>Clockify: GET /workspaces
    Clockify-->>Truto: [{id: "ws_123", name: "Main"}]
    Truto-->>ChatGPT: Returns workspace list
    
    ChatGPT->>Truto: call list_all_clockify_workspace_projects (workspace_id: "ws_123")
    Truto->>Clockify: GET /workspaces/ws_123/projects
    Clockify-->>Truto: [{id: "proj_456", name: "Acme Dashboard"}]
    Truto-->>ChatGPT: Returns project IDs
    
    ChatGPT->>Truto: call create_a_clockify_workspace_time_entry
    Truto->>Clockify: POST /workspaces/ws_123/time-entries
    Clockify-->>Truto: {id: "entry_789", status: "created"}
    Truto-->>ChatGPT: Confirms creation
    ChatGPT-->>User: "I have logged 4 hours to the Acme Dashboard project."

The agent dynamically discovers the workspace, searches the project list to resolve "Acme Corp dashboard" to proj_456, constructs the ISO-8601 timestamps, and submits the final payload.

Scenario 2: Automated Invoicing from Time Logs

Financial workflows require high accuracy. An agent can pull time reports and immediately convert them into draft invoices.

"Calculate all unbilled time for client TechStart this month and generate an invoice for them."

sequenceDiagram
    participant User as User
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP Server

    User->>ChatGPT: "Generate an invoice for TechStart..."
    ChatGPT->>Truto: call list_all_clockify_workspaces
    Truto-->>ChatGPT: Returns workspace_id: "ws_123"
    
    ChatGPT->>Truto: call list_all_clockify_workspace_clients (workspace_id: "ws_123")
    Truto-->>ChatGPT: Returns client_id: "client_999"
    
    ChatGPT->>Truto: call create_a_clockify_reports_detailed (workspace_id: "ws_123", client: "client_999")
    Truto-->>ChatGPT: Returns time entries and totals
    
    ChatGPT->>Truto: call create_a_clockify_workspace_invoice (workspace_id: "ws_123", payload: {...})
    Truto-->>ChatGPT: Returns generated invoice data
    ChatGPT-->>User: "I found 15 unbilled hours for TechStart. I have generated Invoice #0045 for $2,250."

Security and Access Control

Giving an LLM access to your financial and time-tracking data requires strict boundaries. Truto provides four distinct mechanisms to lock down your Clockify MCP servers.

• Method Filtering: Restrict servers to specific operations using config.methods. Pass ["read"] to allow only get and list operations, ensuring the LLM can generate reports but cannot accidentally delete projects or issue bogus invoices.
• Tag Filtering: Group tools by functional area using config.tags. By passing ["time_entries"], you explicitly block the agent from touching the expenses or users endpoints.
• Secondary Authentication: Enable require_api_token_auth to force the client to pass a valid Truto API token in addition to the server URL. This prevents unauthorized execution if the MCP URL is exposed in client logs.
• Automated Expiration: Pass an ISO datetime to the expires_at field to create ephemeral servers. Once the timestamp is reached, automatic infrastructure alarms purge the token, instantly revoking the LLM's access.

Next Steps for AI Workflow Automation

Integrating ChatGPT with Clockify via a custom-built MCP server means accepting the burden of API maintenance, schema drift, and authentication failures. By generating your servers dynamically through Truto, you abstract away the underlying complexity of the Clockify API and provide your agents with clean, schema-driven tools.

Design your filters carefully, ensure your application handles HTTP 429 rate limit headers with strict backoff logic, and isolate read-only reporting servers from read-write invoicing servers.

Stop managing boilerplate API wrappers. Let Truto generate secure, AI-ready integration layers so you can focus on building intelligent agent workflows.