@togglhq/mcp

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-blocks, 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.

License

Proprietary Toggl software. See LICENSE and Toggl legal terms.