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

workspace_id defaults to the configured workspace and project_id defaults to the configured project; explicit arguments always win. The default project is used only where it belongs: tracking in another workspace never inherits it, and with no workspaceId configured it is applied only if the resolved workspace owns that project.

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: Traggo MCP

Configuration

Credentials live in a per-tool file under your home directory, matching the other yt-* MCP servers. TOGGL_API_KEY may supply the token instead, so the file is optional in CI or containers.

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

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

An API token must come from one of the two sources, otherwise the server exits with a message naming the file to create. workspaceId and projectId are file-only settings and both are optional: omit workspaceId if you only have one workspace, and omit projectId if you do not want a default project.

projectId is used only where it belongs, and is verified against the workspace before any write, so an entry never lands in the wrong project. When workspaceId is set, the project applies while tracking in that workspace and a stale id fails with INVALID_PROJECT_ID; naming another workspace_id never inherits it. Without workspaceId, the project is applied when the resolved workspace owns it and ignored when it does not; that check costs an extra request per write, and the result carries a notice when the project was skipped.

Project-local defaults

Pass --settings <file> on the MCP command to select a project-local JSON file that overrides workspaceId and projectId for that project only, without duplicating the API token:

{
  "workspaceId": 1234567,
  "projectId": 7654321
}

The token always comes from TOGGL_API_KEY or the credentials file; an apiToken key in the settings file is ignored. A relative path resolves against the server's working directory, and the file is read once at startup. Keep the file out of version control so no Toggl ids or personal tracking defaults appear in tracked repository files.

Precedence, highest first:

1. explicit tool arguments (workspace_id, project_id)

2. the --settings file

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

Each key falls back on its own: a settings file with only projectId keeps the credentials file's workspaceId, and a null value counts as unset. Without --settings nothing changes. A missing or malformed settings file, or an id that is not a positive integer, stops the server with the path and key named.

TOGGL_DEFAULT_WORKSPACE_ID was removed in 0.5.0; put workspaceId in the credentials file instead.

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, the --settings precedence, 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,
  "projectId": 216478744
}

workspaceId and projectId are optional. Alternatively set TOGGL_API_KEY in the environment to supply only the token — the file still holds the defaults.

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.

To give one project its own defaults without touching the user-wide file, add --settings pointing at an ignored project file:

"command": ["npx", "-y", "yt-toggl-mcp", "--settings", ".yt-toggl.json"]

.yt-toggl.json then holds only {"workspaceId": 1234567, "projectId": 7654321}; the token still comes from the credentials file.

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.