Toggl 2.0 MCP Server

A local MCP (Model Context Protocol) server that connects to the Toggl 2.0 API. Works with any MCP client including Claude Code and Claude Desktop.

The server supports MCP 2026-07-28 and keeps compatibility with legacy MCP clients. JSON tool results include structuredContent for modern clients and a text fallback for older clients.

One-click install

On first use, call the auth MCP tool to sign in (opens your browser). For Claude Code and Claude Desktop, see Add to your MCP client below.

Install

npm install @togglhq/mcp
# or: pnpm add @togglhq/mcp

Authenticate once the MCP server is connected — call the auth tool (opens your browser). Or from a terminal:

npx @togglhq/mcp auth

For one-off runs without a local install: npx -y @togglhq/mcp auth.

Add to your MCP client

Claude Code

claude mcp add toggl-focus -- npx @togglhq/mcp

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "toggl-focus": {
      "command": "npx",
      "args": ["@togglhq/mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Authentication

Uses OAuth2 with PKCE via the Toggl Accounts service. Credentials are stored in ~/.toggl/focus-tools.json (mode 0600). Access tokens refresh automatically — call auth again (or run npx @togglhq/mcp auth) to switch workspaces or if your refresh token expires (after 4 weeks of inactivity).

Upgrading from an older version? Sessions previously stored at ~/.toggl-focus-mcp/config.json are still read automatically — no re-authentication needed.

Unified config vs legacy file: MCP logout only removes credentials when there is a matching profile row under ~/.toggl/focus-tools.json with active.mcp set. Call auth once to migrate into the unified file if logout reports nothing was cleared (or run npx @togglhq/mcp auth from a terminal).

CI or headless environments

Set TOGGL_API_TOKEN to a personal Toggl API key (toggl_sk_…, from Toggl 2.0 Settings → API token). It takes precedence over any OAuth profile: no browser opens, nothing refreshes, and nothing is written to ~/.toggl/focus-tools.json.

claude mcp add toggl-focus \
  -s user \
  -e TOGGL_API_TOKEN=<your-api-key> \
  -e TOGGL_ORGANIZATION_ID=<your-org-id> \
  -- npx @togglhq/mcp

| Variable | Required | Default when unset | | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------- | | TOGGL_API_TOKEN | Yes | OAuth profile from auth | | TOGGL_ORGANIZATION_ID | Usually | The organization last selected in Toggl's hosted MCP, if it is for the same workspace; otherwise an error | | TOGGL_WORKSPACE_ID | No | Your current Toggl 2.0 workspace | | TOGGL_USER_ID | No | Looked up from the API key |

API keys cannot list organizations, so set TOGGL_ORGANIZATION_ID unless the default above applies. App URLs read focus.toggl.com/<organization_id>/workspaces/<workspace_id>/…. The server checks the key and the organization/workspace pair at startup and reports a revoked key or a missing org membership by name.

API keys only reach the Toggl 2.0 API. Tools that call Toggl Accounts return requires OAuth sign-in (run auth) in this mode: org-invitations, org-members, org-time-off-me, org-workspaces, shared-holidays, shared-status, shared-working-hours, and workspace-list with refresh: true. workspace-switch, profile-switch and profile-remove are disabled, and auth, logout and profile-list report token mode instead of touching saved profiles. To use those tools, unset TOGGL_API_TOKEN and run npx @togglhq/mcp auth.

The toggl CLI (@togglhq/cli) honours the same variables; --workspace-id overrides TOGGL_WORKSPACE_ID there. The key is never logged and is redacted from error reports.

Tools

Entity tools

One tool per domain (for example tasks, projects, time-entries, organization). Each tool accepts:

• action (required)
• data (optional)
• confirm_token (optional) — second step for mutating operations
• dry_run (optional) — validates input without calling the API

Mutation confirmation: mutating tools return confirm_required with a confirm_token on the first call; repeat with confirm_token to execute.

Workspace, profiles, and auth

• workspace-list — list workspaces (refresh: true refetches from Accounts)
• workspace-switch — set the active workspace
• profile-list, profile-switch, profile-remove — manage active.mcp in ~/.toggl/focus-tools.json
• auth, logout — sign in or clear the active MCP profile

Agent-oriented guidance ships in skills/toggl-mcp/SKILL.md inside this package.

Privacy & analytics

Public builds may send product analytics: tool name, entity-tool action (for example list), outcome (success, error, or confirmation_required), client, session id and package version. Tool arguments and results are never collected. Signed-in sessions are identified by your Toggl account id so repeat use is not counted as a new person each time; unauthenticated processes stay anonymous.

Disable product analytics:

TOGGL_PRODUCT_ANALYTICS=off

Error reporting is on by default. It sends the tool name, a redacted error category, the stack trace with package-relative file paths, the MCP, Node and OS versions, and sampled request timings without query strings. It never sends tool arguments, results, exception text, console output, your hostname, local paths, or your project's dependency list. Disable it with TOGGL_SENTRY=off, or send it to your own Sentry project with TOGGL_SENTRY_DSN.

License

Proprietary Toggl software. See LICENSE and Toggl legal terms.