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.

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

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

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.