Connect Clockify to Claude: Automate Invoicing, Expenses & Reports

If your team needs to connect Clockify to Claude to automate month-end invoicing, audit workspace expenses, or generate detailed time reports, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC 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 ChatGPT, check out our guide on /connect-clockify-to-chatgpt-track-time-manage-project-workflows/ or explore our broader architectural overview on /connect-clockify-to-ai-agents-manage-teams-schedules-approvals/.

Giving a Large Language Model (LLM) read and write access to a time-tracking and billing platform like Clockify is a non-trivial engineering challenge. You have to handle API token lifecycles, map Clockify's deeply nested Data Transfer Object (DTO) schemas to MCP tool definitions, and deal with specific workspace isolation constraints. Every time Clockify introduces a new DTO version or deprecates a reporting endpoint, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Clockify, connect it natively to Claude, and execute complex billing and reporting 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, the reality of implementing it against specialized B2B APIs is painful. Clockify's API reflects the complexity of managing billable hours, multi-currency invoicing, and complex organizational hierarchies.

If you decide to build a custom Clockify MCP server, here are the specific integration challenges you will face:

Deeply Nested and Hydrated DTOs Clockify relies heavily on specialized Data Transfer Objects (DTOs) for its responses. An endpoint does not just return a flat "Time Entry" record. It might return a TimeEntryWithRatesDtoV1, which embeds complex nested arrays of hourly rates, cost rates, and custom field values. For scheduling, it returns an AssignmentHydratedDtoV1. An LLM cannot reliably guess these complex shapes. A managed MCP server derives tools dynamically from strict documentation schemas, ensuring Claude receives the exact JSON Schema required for properties like ApprovalDetailsDtoV1 and InvoiceOverviewDtoV1.

Experimental Sync Endpoints and Event Delays If you need Claude to audit recently deleted or updated records, you must use Clockify's experimental sync endpoints (e.g., get_single_clockify_entities_updated_by_id). These endpoints carry specific caveats: deleted entities are only reflected in the results about a minute after deletion, and entities that are both created and deleted within the requested date range are excluded entirely. Building logic into a custom MCP server to explain these nuances to an LLM requires extensive prompt engineering. Truto embeds these instructions directly into the dynamic tool descriptions.

Multipart/Form-Data vs JSON Payloads While 95% of the Clockify API accepts standard application/json, specific endpoints break this pattern. For example, attaching a receipt to an expense (create_a_clockify_workspace_expense) or uploading file attachments requires multipart/form-data. Handling multipart encoding over an MCP JSON-RPC connection requires a robust proxy layer. Truto's proxy API handles the schema mapping and encoding automatically, presenting a unified JSON interface to Claude.

Rate Limits and 429 Handling Clockify enforces strict rate limits on report generation and bulk updates. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Clockify API returns HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The AI agent or calling client (Claude) is entirely responsible for implementing retry and backoff logic. Do not expect the MCP server to absorb these errors.

Generating the Managed MCP Server for Clockify

Truto dynamically derives MCP tools from the integration's internal resource definitions and documentation schemas. A tool only appears in the MCP server if it has a corresponding documentation entry, acting as a strict quality gate.

Each MCP server is scoped to a single integrated account. The server URL contains a cryptographically hashed token that authenticates requests, meaning the URL alone is enough to serve tools securely.

You can generate the MCP server URL in two ways.

Method 1: Via the Truto UI

For administrators and non-developers, the Truto dashboard provides a one-click deployment:

1. Navigate to the Integrated Accounts page and select your connected Clockify account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., Name: "Clockify Finance Agent", Methods: "Read and Write").
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For developers building programmatic onboarding flows, you can generate the server via a POST request. This endpoint validates the configuration, hashes the token securely in Cloudflare KV, and returns the URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clockify Billing AI",
    "config": {
      "methods": ["read", "write"],
      "tags": ["invoices", "expenses", "reports"]
    }
  }'

Response:

{
  "id": "abc-123",
  "name": "Clockify Billing AI",
  "config": {
    "methods": ["read", "write"],
    "tags": ["invoices", "expenses", "reports"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you must register it with your LLM client. Truto exposes standard JSON-RPC 2.0 endpoints that are natively compatible with MCP clients.

Method A: Via the Claude UI (or ChatGPT Developer Mode)

If you are using Claude's web interface or ChatGPT's custom connectors:

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server (or in ChatGPT: Settings -> Apps -> Advanced settings -> Developer mode -> Add Custom Connector).
2. Enter a recognizable name (e.g., "Clockify Production Workspace").
3. Paste the Truto MCP URL generated in the previous step.
4. Click Add. The client will automatically send an initialize request and populate the available tools.

Method B: Via Manual Config File (Claude Desktop)

For local development using Claude Desktop, you can configure the MCP server using Server-Sent Events (SSE) via the @modelcontextprotocol/server-sse package.

Edit your claude_desktop_config.json file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop. The application will discover the Clockify tools dynamically on every tools/list request.

Clockify Hero Tools for AI Agents

When Claude lists tools, Truto maps Clockify's REST endpoints into descriptive, snake_case function names. Query and body schemas share a flat input namespace during tool execution, allowing Claude to pass all required arguments seamlessly.

Here are the most high-leverage Clockify tools for billing and reporting automation.

1. Generate Detailed Time Reports

Tool: create_a_clockify_reports_detailed

Clockify's reporting API requires generating an object based on specific date ranges and filters. This tool submits a DetailedReportFilterV1 payload to return precise time entry data. Note that on free plans, the report interval is limited to one month.

"Claude, generate a detailed time report for workspace ID '64b1f...' from October 1st to October 31st. Filter the results to only include billable entries for the 'Website Redesign' project."

2. Create Workspace Invoices

Tool: create_a_clockify_workspace_invoice

This tool drafts a new invoice based on the CreateInvoiceRequest schema. It requires the workspace ID, client ID, currency, due date, issued date, and an invoice number.

"Draft a new USD invoice for client ID 'c_9982' in workspace '64b1f...'. Set the issue date to today, the due date to Net 30, and assign it invoice number 'INV-2026-104'."

3. Fetch Audit Logs

Tool: get_single_clockify_workspace_audit_log_by_id

Compliance and security workflows rely heavily on audit logs. This tool retrieves a paginated PageableV1ListAuditLogDtoV1 report containing actions, authors, and timestamps for workspace modifications.

"Pull the audit log report for the current workspace covering the last 7 days. I need to see if any user roles were modified or if any time-off policies were deleted."

4. Duplicate Existing Invoices

Tool: clockify_workspace_invoices_duplicate

Often, recurring billing requires copying an existing invoice structure rather than building a new one from scratch. This tool duplicates an invoice within a workspace, preserving line items and tax configurations.

"Take invoice ID 'inv_5541' and duplicate it. Return the new invoice ID and the status of the newly created draft."

5. List Workspace Expenses

Tool: list_all_clockify_workspace_expenses

Retrieves a collection of expense records (ExpensesAndTotalsDtoV1). This is critical for finance teams needing to audit out-of-pocket costs submitted by contractors or employees before running payroll.

"List all expenses submitted in the current workspace. Group them by category and calculate the total amount pending approval."

6. Create Workspace Expense (with Receipts)

Tool: create_a_clockify_workspace_expense

Submits a new expense record. Because Clockify requires multipart/form-data for expense file attachments, the Truto proxy layer handles the encoding translation automatically when this tool is invoked by Claude.

"Log a new expense for $45.50 under the 'Travel' category. The expense was incurred on October 15th for client 'Acme Corp'."

7. Fetch Invoice Settings

Tool: list_all_clockify_invoices_settings

Before modifying or generating invoices in bulk, an agent should check the workspace's base invoice settings (e.g., default tax rates, currency, label preferences) using this tool.

"Retrieve the invoice settings for the workspace. What is the default tax percentage and the standard payment terms configured?"

To view the complete inventory of Clockify tools, supported methods, and schema requirements, visit the Truto Clockify Integration Reference.

Workflows in Action

Connecting tools is only half the battle. The real value of an MCP server is enabling Claude to orchestrate multi-step business logic autonomously.

Scenario 1: Month-End Invoice Generation (Billing Ops)

User Prompt:

"It's the end of the month. Please generate a detailed time report for October for client ID 'c_102' in workspace 'w_991'. Calculate the total billable amount, and draft a new invoice for them using that amount with Net 15 terms."

Execution Steps:

1. Claude calls create_a_clockify_reports_detailed, passing the dateRangeStart, dateRangeEnd, and detailedFilter (scoped to the client ID).
2. Claude analyzes the returned TimeEntryDetailedReportDto to calculate the aggregate billable total based on the tracked hours and user cost rates.
3. Claude calls create_a_clockify_workspace_invoice with the client ID, the calculated total, and a dueDate 15 days in the future.
4. Claude returns a confirmation to the user with the new Invoice ID.

sequenceDiagram
  participant User
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Clockify as Clockify API
  User->>Claude: "Generate month-end report and draft invoice"
  Claude->>Truto: Call create_a_clockify_reports_detailed
  Truto->>Clockify: POST /workspaces/{id}/reports/detailed
  Clockify-->>Truto: DetailedReportDtoV1
  Truto-->>Claude: Tool Response (JSON string)
  Claude->>Truto: Call create_a_clockify_workspace_invoice
  Truto->>Clockify: POST /workspaces/{id}/invoices
  Clockify-->>Truto: InvoiceOverviewDtoV1
  Truto-->>Claude: Tool Response (Invoice ID)
  Claude-->>User: "Invoice #1042 created successfully."

Scenario 2: Expense Auditing and Reconciliation (Finance Admin)

User Prompt:

"Audit the expenses for workspace 'w_991' over the last 30 days. Identify any expenses submitted over $500, and check the audit log to see who approved them."

Execution Steps:

1. Claude calls list_all_clockify_workspace_expenses to pull all recent expense records.
2. Claude filters the returned payload in-memory, identifying the specific IDs of expenses exceeding the $500 threshold.
3. Claude calls get_single_clockify_workspace_audit_log_by_id, querying the PageableV1ListAuditLogDtoV1 for approval actions related to those specific expense IDs.
4. Claude presents a formatted summary of high-value expenses and the managers who signed off on them.

Security and Access Control

Handing an LLM unrestricted access to a billing platform is a massive security risk. Truto's MCP servers provide strict, configurable boundaries:

• Method Filtering: Enforce read-only access by configuring the MCP server with methods: ["read"]. The tool generator will automatically skip endpoints like create_a_clockify_workspace_invoice, physically preventing the LLM from mutating data.
• Tag Filtering: Restrict the AI to specific operational domains. Passing tags: ["expenses"] ensures the server only exposes expense-related tools, hiding user directory or project configuration endpoints.
• Dual-Layer Authentication: Enable require_api_token_auth: true when generating the server. This forces the MCP client to pass a valid Truto API token in the Authorization header alongside the secure URL, preventing unauthorized usage if the URL leaks.
• Ephemeral Environments: Use the expires_at field to create temporary, short-lived MCP servers. Truto schedules cleanup alarms using Durable Objects, automatically deleting the token from Cloudflare KV and the database the moment it expires, leaving zero stale credentials behind.

Beyond Hardcoded API Integrations

The traditional approach to AI integrations - writing custom Python scripts, mapping individual endpoints to LangChain tools, and battling OAuth token expiration - does not scale. When Clockify updates a DTO schema or deprecates an experimental endpoint, hardcoded integrations break silently.

By leveraging dynamic, documentation-driven MCP servers, you shift the burden of schema maintenance and proxy execution to the infrastructure layer. Claude gets an up-to-date, strictly typed interface to Clockify, and your engineering team gets out of the business of writing point-to-point connector code.