---
name: toggl-mcp
description: Use the Toggl 2.0 MCP server to read and mutate Toggl 2.0 data (tasks, projects, time blocks, time entries, saved views, custom fields, attachments, organization and org-* domains, org-time-off-me, shared-status/holidays/working-hours tools), manage workspaces and saved profiles, authenticate, and mirror CLI-style workflows from an MCP client. Trigger when the user connects through Model Context Protocol tools rather than the terminal, or asks how to use toggl-focus MCP tools, confirm_token, dry_run, file uploads/downloads, workspace refresh, or profile switching.
---

# Toggl 2.0 MCP

The MCP server exposes **entity tools** (one tool per domain, for example `tasks`, `projects`) plus **workspace**, **profile**, and **auth** tools. Behavior aligns with the shared `@toggl/operations` catalog used by `toggl` CLI—see the `toggl-cli` skill for terminal equivalents (`toggl --json`, `--dry-run`, etc.).

## Operating rules

- Prefer **list** / **get** before mutating when IDs are unknown.
- Entity calls use **`action`** plus optional **`data`** shaped for that action. Tool schemas list valid `action` values.
- **`dry_run: true`** validates input and returns `{ dry_run, operation, input }` without calling the API (like CLI `--dry-run`).
- **Mutations** (non-read operations): first call returns **`confirm_required`** and **`confirm_token`**; repeat the same arguments with **`confirm_token`** to execute once. **`dry_run: true`** skips the API and does not require a token.
- Use **`workspace-list`** with **`refresh: true`** when a workspace is missing from cache (same idea as `toggl workspace list --refresh`).
- **`profile-list`**, **`profile-switch`**, **`profile-remove`** control **`active.mcp`** in `~/.toggl/focus-tools.json`. Profiles are shared with the CLI; removing a profile removes it for both.
- **`profile-remove`** is destructive: first call returns **`confirm_required`** + **`confirm_token`**; call again with the same **`profile_name`** and **`confirm_token`** (same pattern as entity mutations).
- After **`auth`**, credentials use the same derived profile naming as CLI (`environment-userId`). **`logout`** clears the MCP active profile row only when **`active.mcp`** and that profile exist in **`~/.toggl/focus-tools.json`**. Older setups may still load **`~/.toggl-focus-mcp/config.json`** via compatibility—if logout says nothing was cleared, run **`auth`** once to migrate into the unified file, or delete the legacy path manually if discarding that session.
- **Files cross the tool boundary as local paths** (the server runs on the user's machine): upload attachments with `attachments-create` / `attachments-bulk-create` passing **`file_path`** / **`file_paths`** (mime inferred from extension, 20 MB cap); download with `attachments-view` passing **`save_to`** (refuses to replace an existing file unless **`overwrite: true`**).
- **List actions paginate** with `page` / `per_page` where the API supports it; request a page size instead of walking every page when summarizing large workspaces.
- Some mutations need elevated rights: **custom-fields mutations are workspace-admin-only** (expect 403 otherwise).

## Tools overview

- **Entity domains**: tool names match `@toggl/operations` `mcp.entityTool` strings (examples: **`tasks`**, **`projects`**, **`saved-views`**, **`custom-fields`**, **`organization`**, **`org-invitations`**, **`shared-working-hours`**). Each tool accepts **`action`** values surfaced in server instructions and tool descriptions (hyphenated multi-word actions such as `bulk-patch`, `attachments-list`). Curated routing may group endpoints under the most helpful domain (for example composite flows and attachments under **`projects`** / **`tasks`**).
- **Workspace/auth**: **workspace-list** (optional `refresh`), **workspace-switch**, **profile-list**, **profile-switch**, **profile-remove**, **auth**, **logout**.
- Some low-level endpoints are omitted from the public tool surface.

## Install

```bash
npm install @togglhq/mcp
npx @togglhq/mcp auth
```

Pair with the `toggl-cli` skill for terminal equivalents (`toggl --json`, `--dry-run`, etc.).

## Read next

- Bundled package README (in your `node_modules/@togglhq/mcp` install)
- `toggl-cli` skill for CLI parity