yt-toggl-mcp

A small, self-hosted MCP server for Toggl Track (API v9). It runs over stdio and exposes time tracking, projects/clients, and reporting to any MCP client.

No telemetry. The only network egress is to api.track.toggl.com. Workspace-level tokens are stripped from every response and user emails are masked.

Tools

period accepts today, yesterday, week, lastWeek, month, lastMonth. Ranges are interpreted in local time and end_date is inclusive at the tool boundary. since takes unix seconds and, per Toggl, also returns entries deleted since that time.

Toggl enforces a sliding-window request quota per user per organization; on 402 the error result carries quota_remaining and quota_resets_in_seconds.

toggl_report clips every entry to the requested range, so an entry crossing a boundary is neither double-counted nor dropped. It scans backward in 84-day windows and respects Toggl's historical retention boundary: if it reaches that boundary it returns incomplete: true together with incomplete_reason, rather than reporting a silently short total. Any other error is propagated.

Related MCP server: solidtime-mcp-server

Configuration

Credentials live in a per-tool file under your home directory, matching the other yt-* MCP servers. Environment variables take precedence, so the file is optional in CI or containers.

~/.yt-toggl-mcp/credentials.json:

{
  "apiToken": "<your token>",
  "workspaceId": 1234567
}

A token must come from one of the two sources, otherwise the server exits with a message naming the file to create. workspaceId is optional — omit it if you only have one workspace.

Install

Prerequisites: Node.js >=20.19.0 and a Toggl Track API token from track.toggl.com/profile (scroll to the bottom → "Click to reveal").

npm

npx -y yt-toggl-mcp

Any MCP client that speaks stdio works. Generic client config:

{
  "mcpServers": {
    "yt-toggl-mcp": {
      "command": "npx",
      "args": ["-y", "yt-toggl-mcp"]
    }
  }
}

yt-toggl-mcp --help prints the credential path and the environment variables; --version prints the version. Both write to stderr, since stdout carries the MCP protocol.

opencode

1. Create the credentials file

Write ~/.yt-toggl-mcp/credentials.json (Windows: C:\Users\<you>\.yt-toggl-mcp\credentials.json):

{
  "apiToken": "<your token>",
  "workspaceId": 1234567
}

workspaceId is optional. Alternatively set TOGGL_API_KEY (and optionally TOGGL_DEFAULT_WORKSPACE_ID) in the environment — env vars win over the file.

2. Register the server

Add this to ~/.config/opencode/opencode.jsonc (Windows: C:\Users\<you>\.config\opencode\opencode.jsonc) under the existing mcp key:

{
  "mcp": {
    "yt-toggl-mcp": {
      "type": "local",
      "command": ["npx", "-y", "yt-toggl-mcp"]
    }
  }
}

No environment block is needed: the server reads its own credentials file, like yt-gmail-mcp and yt-zoho-mcp.

3. Restart opencode

Config is read once at startup and is not hot-reloaded, so the server only loads after a restart.

4. Verify

Ask opencode to call toggl_check_auth. It should return your (masked) account and workspace list. A quick win after that: ask "what am I currently tracking?".

Development

npm install
npm run build
npm run lint
npm test

npm test runs the Vitest suite with HTTP mocked, so no token or live calls are needed.

node dist/index.js runs the built server locally — it reads the same credentials file described above. npm run dev watches the source with tsx instead of building.

License

MIT © yentsun — see LICENSE.