Connect Toggl to Claude: Analyze Team Productivity and Reports

If your team needs to connect Toggl to Claude to analyze team productivity, automate time-entry auditing, or generate cross-project billing reports, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Toggl's complex 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 sibling guide on connecting Toggl to ChatGPT, or explore our broader architectural overview on connecting Toggl to AI Agents.

Giving a Large Language Model (LLM) read and write access to a time-tracking ecosystem like Toggl is a significant engineering challenge. You have to handle API token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Toggl's strict, workspace-centric data models. Every time Toggl updates a reporting endpoint or deprecates a V8 resource, 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 Toggl, connect it natively to Claude Desktop, and execute complex time-tracking workflows using natural language.

The Engineering Reality of the Toggl 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 Toggl's APIs is painful. Toggl Track is divided into two distinct API surfaces: the standard Track API (currently V9) and the Reports API.

If you decide to build a custom MCP server for Toggl, you own the entire integration lifecycle. Here are the specific challenges you will face:

The Workspace-Centric Data Model Toggl's data hierarchy is strict: Organizations contain Workspaces, Workspaces contain Projects, and Projects contain Tasks and Time Entries. Almost every useful endpoint in the Toggl API requires a workspace_id in the URL path. An LLM has no inherent context of this hierarchy. If it tries to create a project, it will fail unless your MCP server explicitly guides it to fetch the workspace_id first. A managed MCP server exposes tools with strictly defined JSON schemas that enforce these dependencies, ensuring Claude collects the required IDs before attempting mutations.

Header-Based Cursor Pagination in Reports While standard REST APIs often return pagination cursors in the JSON response body, Toggl's Reporting API frequently relies on HTTP headers. For example, when searching time entries in the Summary Reports API, the cursor for the next page is returned in the X-Next-ID HTTP header. Claude cannot read HTTP response headers natively. If you build this yourself, you must write custom middleware to extract this header, inject it into the JSON payload, and update the MCP tool schema to document how the LLM should pass it back in the next request.

Strict Rate Limiting and HTTP 429s Toggl enforces strict rate limits, sometimes restricting requests to 1 per second per IP/token for heavy reporting endpoints. When you hit this limit, Toggl returns an HTTP 429 Too Many Requests. Note on how Truto handles this: Truto does not automatically retry, throttle, or absorb these rate limit errors. Instead, when Toggl returns a 429, Truto passes that error directly to Claude, normalizing the upstream rate limit information into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (your agent framework or Claude) is responsible for implementing the necessary retry and backoff logic.

How to Create the Toggl MCP Server

Truto derives MCP tools dynamically from your connected Toggl account. Rather than hand-coding tool definitions, Truto uses Toggl's API documentation and OpenAPI schemas to auto-generate a curated list of tools.

You can generate the MCP server URL using either the Truto UI or the API.

Method 1: Via the Truto UI

For teams who want a no-code setup, you can generate the MCP server directly from the dashboard:

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Toggl Track integration.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., name the server "Toggl Reporting", restrict methods to read only, or filter by specific tags).
6. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the API

For programmatic generation - ideal for multi-tenant SaaS applications spinning up ephemeral AI agents for users - you can create the server via a POST request.

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": "Claude Toggl Analyst",
    "config": {
      "methods": ["read", "write"],
      "tags": ["reports", "time_entries"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API validates that the Toggl integration is "AI-ready" (meaning it has documented resources), hashes a secure token, and returns the endpoint:

{
  "id": "mcp_8f7e6d5c",
  "name": "Claude Toggl Analyst",
  "config": {
    "methods": ["read", "write"],
    "tags": ["reports", "time_entries"]
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL is fully self-contained. It encodes the integrated account and the tool filters.

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you need to register it with Claude. There are two primary ways to do this, depending on your environment.

Method A: Via the Claude UI

If you are using Claude Desktop or the enterprise web interface:

1. Open Settings.
2. Navigate to Integrations (or Connectors).
3. Click Add MCP Server (or Add custom connector).
4. Name the connection (e.g., "Toggl via Truto").
5. Paste the Truto MCP URL into the endpoint field.
6. Click Add.

Claude will immediately perform a handshake with the Truto MCP router, requesting tools/list, and populate its context window with the available Toggl operations.

Method B: Via Manual Config File

If you are running Claude Desktop locally for development, or deploying headless agents via Cursor, you can update the MCP configuration file directly. Truto MCP servers operate over standard Server-Sent Events (SSE).

Locate your claude_desktop_config.json file (typically found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the server:

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

Restart Claude Desktop. The tools will now be available in your chats.

6 Hero Tools for Toggl AI Workflows

The Toggl API exposes dozens of endpoints. Truto maps these into discrete, highly documented MCP tools. Here are 6 high-leverage "hero tools" your AI agent can use to automate time and project management.

list_all_toggl_workspace_projects

This tool retrieves a paginated list of all projects within a specific Toggl workspace. It supports extensive filtering (active status, billable, client IDs, updated since) which helps Claude narrow down large datasets.

Usage notes: Claude must first know the workspace_id. If it doesn't have it, it should independently call the workspaces list tool first.

"Claude, list all active, billable projects in my primary Toggl workspace. I need their internal IDs so we can run a time report on them."

list_all_toggl_workspace_time_entries

This tool lists time entries for the authenticated user within a workspace. It returns critical fields like duration, description, and start/stop timestamps.

Usage notes: The API requires workspace_id. It is excellent for auditing what a specific user has been working on recently.

"Pull my time entries from this week in the engineering workspace. Group them by project and tell me how many hours I logged against the 'Frontend Refactor' task."

create_a_toggl_workspace_time_entry

This tool allows Claude to start a new time entry or log past time in a Toggl workspace. It accepts the workspace_id, description, project_id, and start/duration parameters.

Usage notes: If duration is negative, Toggl treats the time entry as "currently running". Claude understands this nuance based on the dynamically generated schema descriptions.

"Start a Toggl timer in the design workspace for 'Writing API documentation'. Assign it to the Developer Portal project."

toggl_summary_reports_search_time_entries

This is a heavy-duty reporting tool. It searches time entries across the entire workspace for summary reporting, allowing filtering by date ranges, users, clients, and tags.

Usage notes: This tool handles the complex X-Next-ID pagination automatically via Truto's proxy layer. It is perfect for generating weekly team utilization summaries.

"Run a summary report for last month in the agency workspace. Show me the total billable hours logged by John and Sarah, broken down by client."

list_all_toggl_organization_users

This tool lists all users in a Toggl organization, returning their email, role, group, and workspace memberships.

Usage notes: Note the parameter shift - this requires organization_id, not workspace_id. Claude relies on the tool schema to know exactly which ID to pass.

"Fetch a list of all active users in our Toggl organization. Tell me who has organization admin privileges."

toggl_workspace_timesheets_update_timesheet

This tool changes the status of a Toggl timesheet (e.g., submit, approve, reject, or reopen), using the setup_id and period start_date.

Usage notes: This is a premium feature in Toggl. The agent must provide the specific status string. This enables autonomous approval workflows based on predefined logic.

"Review the submitted timesheets for the engineering team from last week. If the total hours are under 45, approve them using the update timesheet tool."

For a complete inventory of available tools, resource schemas, and query parameters, view the full Toggl integration page.

Workflows in Action

Exposing raw tools is only half the battle. The real power of an MCP server is orchestrating these tools into complex, multi-step workflows.

Here is how Claude orchestrates Toggl tools in practice.

Workflow 1: The Automated Weekly Productivity Audit

Project managers spend hours exporting CSVs to determine if teams are over-indexing on non-billable work. Claude can automate this entirely.

"Claude, analyze our team's time entries in the 'Agency' workspace for the past 7 days. Identify any users who logged more than 20% of their time to non-billable projects, and summarize the total billable value generated."

How Claude executes this:

1. Calls get_single_toggl_workspace_by_id (or similar list tool) to resolve the "Agency" workspace to a numeric ID (e.g., 123456).
2. Calls toggl_summary_reports_search_time_entries passing workspace_id: 123456, start_date, and end_date.
3. The MCP server delegates the request to Truto, which handles the Toggl authentication and normalizes the payload.
4. Claude ingests the JSON summary data, calculates the billable vs. non-billable ratios per user, and returns a formatted markdown report directly in the chat.

sequenceDiagram
    participant User
    participant Claude as Claude
    participant TrutoMCP as Truto MCP
    participant Toggl as Toggl API
    
    User->>Claude: "Analyze team time entries for past 7 days..."
    Claude->>TrutoMCP: Call toggl_summary_reports_search_time_entries (workspace_id, dates)
    TrutoMCP->>Toggl: POST /reports/api/v3/workspace/{id}/search/time_entries
    Toggl-->>TrutoMCP: 200 OK (Summary JSON)
    TrutoMCP-->>Claude: Returns formatted tool result
    Claude->>User: Renders Billable/Non-Billable Markdown Report

Workflow 2: Context-Aware Time Logging

Developers constantly forget to log their time. Instead of context-switching into the Toggl web app, they can ask Claude to handle it based on casual conversation.

"Claude, I just spent two hours fixing the database migration bug for the 'Acme Corp' project. Can you log that time for me?"

How Claude executes this:

1. Calls list_all_toggl_workspace_projects with a search filter for "Acme Corp" to retrieve the exact project_id.
2. Calls create_a_toggl_workspace_time_entry passing the resolved project_id, the user's workspace_id, a duration of 7200 (2 hours in seconds), and the description "Fixing database migration bug".
3. Truto executes the proxy request to Toggl.
4. Claude replies: "I've successfully logged 2 hours to the Acme Corp project for the database migration fix."

Security and Access Control

Giving an AI agent access to your financial and time-tracking data requires strict governance. Truto MCP servers provide multiple layers of security to limit blast radius:

• Method Filtering: Configure the server with config.methods: ["read"] to ensure Claude can only execute GET or LIST operations. This prevents the LLM from accidentally deleting projects or stopping running timers.
• Tag Filtering: Restrict tools by functional area using config.tags: ["reports"] to ensure the agent only sees analytics tools, rather than the entire Toggl administrative surface.
• Require API Token Auth: By setting require_api_token_auth: true, the bare MCP URL is no longer enough to connect. The client must also pass a valid Truto API token in the Authorization header, adding a second layer of enterprise authentication.
• Ephemeral Servers: Use the expires_at configuration to create temporary MCP servers. If you are generating a server for a specific CI/CD run or a contractor's temporary agent, the server will self-destruct at the specified ISO datetime, permanently revoking access.

Strategic Wrap-up

Building a custom MCP server for Toggl means dealing with workspace-centric object hierarchies, undocumented HTTP header pagination, and aggressive rate limits. By using a managed MCP architecture, you offload the entire integration lifecycle.

Truto automatically derives tool schemas from Toggl's live documentation, normalizes complex API responses into flat, LLM-friendly structures, and handles the cryptographic token management required to keep your data secure. Your engineering team can stop reading API docs and start building high-value AI workflows.