toggl-mcp

A small local MCP server for the Toggl Track API v9, exposing the operations you actually use day to day:

All the Toggl quirks are baked in: Basic-auth token handling, https://api.track.toggl.com/api/v9 base, RFC3339/YYYY-MM-DD dates, seconds-based durations, default-workspace resolution.

Prerequisites

• Node.js 18+ (built/tested on Node 26).

• A Toggl Track API token — get it at https://track.toggl.com/profile (bottom of the page). This is not the same as a Toggl Focus toggl_sk_… token.

Related MCP server: Lazy Toggl MCP Server

Build

git clone https://github.com/MikeAtPinnacle/toggl-mcp.git
cd toggl-mcp
npm install
npm run build

This compiles to dist/index.js. Note its absolute path — you'll point your MCP client at it below. The examples use /absolute/path/to/toggl-mcp/dist/index.js as a placeholder; on Windows that looks like C:\\path\\to\\toggl-mcp\\dist\\index.js (escape the backslashes in JSON).

The API token

The server reads the token from TOGGL_API_TOKEN (or TOGGL_TRACK_API_TOKEN as a fallback). Auth is HTTP Basic with base64(<token>:api_token) — the server does that for you.

Provide the token via the MCP client's env block (below) so it stays scoped to this server and never collides with anything else.

Register with Claude Desktop

Edit the Claude Desktop config file for your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add (replace the path with your built dist/index.js):

{
  "mcpServers": {
    "toggl": {
      "command": "node",
      "args": ["/absolute/path/to/toggl-mcp/dist/index.js"],
      "env": { "TOGGL_API_TOKEN": "<your_toggl_track_api_token>" }
    }
  }
}

Restart Claude Desktop. The tools appear under the toggl server.

Register with Claude Code

From any project (works on the CLI and the VS Code extension, which share this config):

claude mcp add toggl --scope user \
  --env TOGGL_API_TOKEN=<your_toggl_track_api_token> \
  -- node /absolute/path/to/toggl-mcp/dist/index.js

--scope user makes it available in every project; use --scope local/project to scope it. Verify with claude mcp list.

Usage examples

Once the server is registered, just ask Claude in plain language — it picks the right tool and fills the parameters:

Tool inputs (for direct/programmatic calls)

list_time_entries — dates accept YYYY-MM-DD or RFC3339; end_date is exclusive; both default to the last 7 days. Optionally filter by project_id / task_id, or exclude_tag to skip already-processed entries (all client-side; the Toggl endpoint only takes dates). Each entry includes project_name and task_name (the Toggl task — e.g. a Jira key); output adds per-day, per-project, and per-task totals, and excludes running timers from totals.

// whole range
{ "start_date": "2026-06-22", "end_date": "2026-06-29" }

// one project
{ "start_date": "2026-06-01", "end_date": "2026-07-01", "project_id": 12345678 }

// a day's entries not yet pushed to Jira
{ "start_date": "2026-06-26", "end_date": "2026-06-27", "exclude_tag": "jira-logged" }

Returns a text summary plus structuredContent with { count, total_seconds, entries[] }:

12 entries, total 18h 20m
Per day:
  2026-06-22: 6h 10m
  2026-06-23: 5h 45m

2026-06-22 13:15  0h 45m   Design review  [Website]
...

list_projects — find the project_id the write tools need.

{ "active_only": true }

create_task — project_id + name required; workspace_id defaults to your default workspace.

{ "project_id": 12345678, "name": "Write design doc", "estimated_seconds": 7200 }

log_time — log a completed entry, or start a running timer.

// completed entry (90 minutes, ending now)
{ "description": "Code review", "project_id": 12345678, "duration_seconds": 5400 }

// running timer (starts now; duration becomes -1 server-side)
{ "description": "Standup", "project_id": 12345678, "start_now": true }

start defaults to now (RFC3339 to override). Attach work with project_id and/or task_id. Optional: billable, tags (string names).

tag_time_entry — add (default) or remove tag names on an entry; other tags are preserved.

{ "time_entry_id": 12345678, "tags": ["jira-logged"], "action": "add" }

current_timer — no arguments. Returns the running entry (with elapsed time) or { running: false }.

stop_timer — no arguments stops whatever is running; or target a specific entry.

{ "time_entry_id": 12345678 }

Logging time to Jira (end-of-day worklog flow)

If you name each Toggl task after a Jira ticket (e.g. LEGLINK-142), task_name is the Jira key — so this server gives you the read + dedupe half of an end-of-day "push my tracked time to Jira worklogs" workflow. The Jira write is done by a separate Jira MCP (this server is Toggl-only; make sure yours supports POST /issue/{key}/worklog).

The flow Claude runs:

1. Read the day's loggable entries, skipping ones already pushed: list_time_entries { start_date, end_date, exclude_tag: "jira-logged" } — each entry carries task_name (the Jira key), start, and duration (seconds). Running timers are flagged and excluded from totals; skip them.

2. Write one Jira worklog per entry via your Jira MCP — task_name → issue key, duration → timeSpentSeconds, start → started, description → comment.

3. Mark each pushed entry so it won't be logged twice: tag_time_entry { time_entry_id, tags: ["jira-logged"], action: "add" }

Because step 1 filters exclude_tag: "jira-logged", the job is safe to re-run — already-logged entries are skipped. Entries with no task_id (no Jira ticket) are simply left for you to handle.

Smoke test (no MCP client needed)

export TOGGL_API_TOKEN="<your_toggl_track_api_token>"   # PowerShell: $env:TOGGL_API_TOKEN="..."
npm run build
npm run smoke

Prints your default workspace, first projects, and last-7-days entry count if the token works.

Notes

• stdio server: logs go to stderr only; stdout is reserved for the MCP protocol.

• Running timers: log_time with start_now: true (or no duration_seconds) starts a timer (duration = -1); otherwise it logs a completed entry. Stop it with stop_timer.

• Rate limits: Toggl throttles aggressively (~1 req/s). The client automatically retries 429/5xx with backoff (honoring Retry-After), so bursts of calls degrade gracefully instead of failing.

• Upgrade path: to distribute this without requiring Node on the target machine, repackage as an MCPB bundle.