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: 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 and/or task_id (filtered client-side, since the Toggl endpoint only takes dates). Output includes per-day and per-project breakdowns with resolved project names.

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

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

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).

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 }

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.