ranbot-ai/Toggl Automation

Toggl Automation

Automate your Toggl Track time tracking operations directly from Claude Code. Log time, manage projects and clients, organize with tags, and control workspaces -- all without leaving your terminal.

Toolkit docs: composio.dev/toolkits/toggl

---

Setup

1. Add the Rube MCP server to your Claude Code config with URL: https://rube.app/mcp
2. When prompted, authenticate your Toggl Track account through the connection link provided
3. Start automating your time tracking workflows with natural language

---

Core Workflows

1. Create and Stop Time Entries

Log time with project, task, and tag associations, or start/stop timers.

Tools: TOGGL_CREATE_TIME_ENTRY, TOGGL_PATCH_STOP_TIME_ENTRY

Start a time entry in workspace 123456 for project 78910 tagged "meeting" and "design" with description "Design review session"

Key parameters for TOGGL_CREATE_TIME_ENTRY:

• workspace_id (required) -- target workspace
• created_with (required) -- client application name (e.g., "api_client")
• start (required) -- ISO 8601 timestamp
• stop -- ISO 8601 end time; omit to leave the entry running
• duration -- duration in seconds; omit for running entries
• project_id -- associate with a project
• task_id -- associate with a task
• tags -- array of tag name strings (not IDs)
• description -- description of the work
• billable -- billable status

Key parameters for TOGGL_PATCH_STOP_TIME_ENTRY:

• workspace_id (required) and time_entry_id (required)

2. Manage Projects

Create new projects and list existing ones with client details and pagination.

Tools: TOGGL_CREATE_PROJECT, TOGGL_GET_PROJECTS, TOGGL_GET_PROJECT_DETAILS

Create a private billable project called "Q1 Marketing Campaign" in workspace 123456 for client 78910

Key parameters for TOGGL_CREATE_PROJECT:

• workspace_id (required) and name (required)
• client_id, billable, is_private, active, color
• estimated_hours, rate, fixed_fee, currency (premium features)

Key parameters for TOGGL_GET_PROJECTS:

• workspace_id (required)
• page / page_size (1-200) for pagination
• since / until -- Unix timestamps for modification filtering (last 3 months only)
• clients: true to include full client details

3. Manage Clients

Create and list clients within a workspace.

Tools: TOGGL_CREATE_CLIENT, TOGGL_GET_LIST_CLIENTS

List all active clients in workspace 123456, then create a new client called "Acme Corp"

• TOGGL_CREATE_CLIENT requires workspace_id and name; accepts notes, external_reference
• TOGGL_GET_LIST_CLIENTS requires workspace_id; supports status ("active", "archived", "both") and name (case-insensitive search)

4. Tags and Workspace Preferences

Retrieve tags for categorization and check workspace settings.

Tools: TOGGL_GET_TAGS, TOGGL_GET_WORKSPACE_PREFERENCES

Show me all tags in workspace 123456 and the workspace preferences

• TOGGL_GET_TAGS requires workspace_id; returns tag IDs and names
• TOGGL_GET_WORKSPACE_PREFERENCES requires workspace_id; returns pricing plan and display settings

5. Workspace Discovery

List all workspaces the authenticated user belongs to.

Tool: TOGGL_GET_USER_WORKSPACES

What Toggl workspaces do I have access to?

• No parameters required
• Returns all workspaces with IDs, names, and metadata
• Use this first to discover workspace IDs for other operations

6. User Project Visibility

List projects visible to the authenticated user.

Tool: TOGGL_GET_USER_PROJECTS

Show me all projects I can see across my workspaces

• Returns projects the authenticated user has access to
• Use alongside TOGGL_GET_PROJECTS for workspace-scoped views

---

Known Pitfalls

• Tags use names, not IDs: TOGGL_CREATE_TIME_ENTRY accepts tag names as strings in the tags array, unlike many APIs that use IDs. Use TOGGL_GET_TAGS to verify available tag names.
• created_with is required: Every time entry must include created_with (e.g., "api_client"). Missing this field causes silent failures.
• Duration is in seconds: The duration parameter on time entries is in seconds, not hours. 1 hour = 3600 seconds.
• since timestamp restriction: The since filter on TOGGL_GET_PROJECTS only allows timestamps within the last 3 months. Older queries will be rejected.
• Premium features gated: Custom colors, templates, fixed fees, and hourly rates on projects require a premium Toggl plan. Non-premium accounts will get errors when using these fields.
• Workspace ID required everywhere: Nearly all Toggl tools require workspace_id. Always call TOGGL_GET_USER_WORKSPACES first to resolve it.

---

Quick Reference

| Tool Slug | Description | |---|---| | TOGGL_CREATE_TIME_ENTRY | Create a time entry or running timer (requires workspace_id, `created_wit