toggl-focus-mcp

MCP server for Toggl Focus (2.0) — not Toggl Track 1.0.

Connect Claude, Cursor, Codex, or OpenCode to your Focus workspace with a Bearer API key (toggl_sk_…) and npx. No OAuth browser flow required.

npx -y toggl-focus-mcp

| | | | --- | --- | | Auth | Focus Bearer API key (Authorization: Bearer toggl_sk_…) | | API | https://focus.toggl.com/api | | Transport | stdio MCP | | Node | ≥ 20 (CI / .nvmrc → latest Current) |

Track “API Token” values (Basic Auth / profile token for Track) do not work. Create a Focus / Toggl 2.0 key in settings. Official OAuth MCP: @togglhq/mcp.

Prerequisites

1. A Toggl Focus / 2.0 API key (toggl_sk_…) — shown once when created
2. Your organization ID and workspace ID (strongly recommended)
3. Node.js 20+ (for npx)

Find org/workspace IDs in the Focus URL, e.g.
https://focus.toggl.com/.../organizations/21504582/workspaces/21503801/...

Setting both IDs avoids extra discovery calls and protects against Focus hourly quota limits.

Environment variables

| Variable | Required | Description | | --- | --- | --- | | TOGGL_FOCUS_API_TOKEN | Yes* | Focus API key (toggl_sk_…) | | TOGGL_API_KEY | Yes* | Alias for the Focus API key | | TOGGL_API_TOKEN | Yes* | Additional alias | | TOGGL_ORGANIZATION_ID | Recommended | Default organization ID | | TOGGL_WORKSPACE_ID | Recommended | Default workspace ID | | TOGGL_FOCUS_BASE_URL | No | API base (default https://focus.toggl.com/api) |

* Exactly one of TOGGL_FOCUS_API_TOKEN, TOGGL_API_KEY, or TOGGL_API_TOKEN is required.

Most tools accept optional organization_id / workspace_id arguments that override the env defaults for that call.

Install

Replace toggl_sk_..., 123, and 456 with your real key and IDs.

Claude Code

claude mcp add toggl-focus \
  -e TOGGL_FOCUS_API_TOKEN=toggl_sk_... \
  -e TOGGL_ORGANIZATION_ID=123 \
  -e TOGGL_WORKSPACE_ID=456 \
  -- npx -y toggl-focus-mcp

Verify:

claude mcp list

Claude Desktop

Edit claude_desktop_config.json, then restart Claude Desktop.

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

{
  "mcpServers": {
    "toggl-focus": {
      "command": "npx",
      "args": ["-y", "toggl-focus-mcp"],
      "env": {
        "TOGGL_FOCUS_API_TOKEN": "toggl_sk_...",
        "TOGGL_ORGANIZATION_ID": "123",
        "TOGGL_WORKSPACE_ID": "456"
      }
    }
  }
}

Cursor

Add to project .cursor/mcp.json or your global Cursor MCP settings:

{
  "mcpServers": {
    "toggl-focus": {
      "command": "npx",
      "args": ["-y", "toggl-focus-mcp"],
      "env": {
        "TOGGL_FOCUS_API_TOKEN": "toggl_sk_...",
        "TOGGL_ORGANIZATION_ID": "123",
        "TOGGL_WORKSPACE_ID": "456"
      }
    }
  }
}

Enable the server in Cursor Settings → MCP, then confirm tools like focus_whoami appear.

Codex

CLI (recommended):

codex mcp add toggl-focus \
  --env TOGGL_FOCUS_API_TOKEN=toggl_sk_... \
  --env TOGGL_ORGANIZATION_ID=123 \
  --env TOGGL_WORKSPACE_ID=456 \
  -- npx -y toggl-focus-mcp

Or edit ~/.codex/config.toml (or project .codex/config.toml in a trusted repo):

[mcp_servers.toggl-focus]
command = "npx"
args = ["-y", "toggl-focus-mcp"]

[mcp_servers.toggl-focus.env]
TOGGL_FOCUS_API_TOKEN = "toggl_sk_..."
TOGGL_ORGANIZATION_ID = "123"
TOGGL_WORKSPACE_ID = "456"

To keep secrets out of the file, set them in your shell and forward by name:

[mcp_servers.toggl-focus]
command = "npx"
args = ["-y", "toggl-focus-mcp"]
env_vars = ["TOGGL_FOCUS_API_TOKEN", "TOGGL_ORGANIZATION_ID", "TOGGL_WORKSPACE_ID"]

Shared across Codex CLI, IDE extension, and ChatGPT desktop Codex host. Docs: developers.openai.com/codex/mcp.

OpenCode

Add to opencode.json / opencode.jsonc (project or global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "toggl-focus": {
      "type": "local",
      "command": ["npx", "-y", "toggl-focus-mcp"],
      "enabled": true,
      "environment": {
        "TOGGL_FOCUS_API_TOKEN": "toggl_sk_...",
        "TOGGL_ORGANIZATION_ID": "123",
        "TOGGL_WORKSPACE_ID": "456"
      }
    }
  }
}

You can also reference shell env vars with OpenCode’s {env:VAR} syntax where supported. Docs: opencode.ai/docs/mcp-servers.

Quick start prompts

Once the server is connected, try:

• “Who am I in Toggl Focus?”
• “List my projects”
• “Start a timer on project X”
• “Create a task called Ship MCP docs on project Y”
• “Show time entries for this week”

Creates, updates, deletes, and timer start/stop apply immediately (no confirmation token).

Tools

24 tools. All are Focus/2.0 only. Shared optional args on almost every tool:

| Arg | Type | Notes | | --- | --- | --- | | organization_id | number | Overrides TOGGL_ORGANIZATION_ID | | workspace_id | number | Overrides TOGGL_WORKSPACE_ID | | page | number | Default 1 (list tools) | | per_page | number | Default 50, max 100 (list tools) |

Account & context

focus_whoami

Account metadata + user settings for the authenticated Focus key.

| Arg | Type | Required | Description | | --- | --- | --- | --- | | include_settings | boolean | No | Default true — also fetch GET /users/me/settings | | organization_id / workspace_id | number | No | Optional scope |

focus_get_workspace_context

Resolve and cache organization_id / workspace_id for later tools. Prefer setting both env vars. Does not call the session-only /workspaces/{id}/context endpoint (that returns 403 for API keys).

focus_list_org_users

List organization users (assignee lookup). Read-only.

| Arg | Type | Required | Description | | --- | --- | --- | --- | | filter | string | No | Search name/email | | active_status | string | No | Active-status filter when supported | | page / per_page | number | No | Pagination |

Projects

focus_list_projects

List workspace projects.

| Arg | Type | Description | | --- | --- | --- | | name | string | Filter by project or client name | | archived / completed / pinned | boolean | Status filters | | client_id | number[] | Filter by client IDs | | tag_id | number[] | Filter by tag IDs |

focus_get_project

| Arg | Type | Required | | --- | --- | --- | | project_id | number | Yes |

focus_create_project

Creates immediately. Requires name.

| Arg | Type | Description | | --- | --- | --- | | name | string | Required | | description | string | | | client_id | number | Supported on create | | color | string | | | private / pinned / billable | boolean | | | start_date / end_date | string | YYYY-MM-DD | | tag_ids | number[] | Applied via follow-up PATCH; may be forbidden on some plans/roles — project still creates and a warning is returned | | parent_project_id | number | |

focus_update_project

Partial update (PATCH). Requires project_id. Same optional fields as create, plus nullable client_id and optional archived.

Tasks

focus_list_tasks

| Arg | Type | Description | | --- | --- | --- | | name | string | Name filter | | project_id | number[] | Project IDs | | status_id | number[] | Status IDs | | assignee_user_id | number[] | Assignees | | tag_id | number[] | Tags | | pinned / archived | boolean | | | parent_task_id | number[] | Parent tasks | | include_assignees | boolean | Expand assignees |

focus_get_task

Requires task_id. Optional include_assignees.

focus_create_task

Creates immediately. Requires name.

| Arg | Type | Description | | --- | --- | --- | | name | string | Required | | description / notes | string | | | project_id / parent_task_id / status_id | number | | | assignee_user_ids / tag_ids | number[] | | | estimated_mins | number | | | priority | "none" | "low" | "medium" | "high" | | | pinned / private / billable | boolean | | | start_date / end_date | string | YYYY-MM-DD |

focus_update_task

Partial update. Requires task_id. Same mutable fields as create (all optional).

Live tracking

focus_get_current_timer

Returns the running timer for the workspace, or { "running": false }.

focus_start_timer

Starts immediately. type defaults to "activity".

| Arg | Type | Description | | --- | --- | --- | | type | "activity" | "break" | Default activity | | task_id / project_id | number | | | description | string | | | billable | boolean | | | tag_ids | number[] | | | time_block_id | number | | | start | string | RFC3339; server default = now |

focus_stop_timer

Stops the running timer. Optional end (RFC3339); defaults to current UTC.

Time entries

focus_list_time_entries

Requires a date range. Accepts YYYY-MM-DD or RFC3339 (YYYY-MM-DD is expanded to start/end of day UTC).

| Arg | Type | Required | Description | | --- | --- | --- | --- | | date_from | string | Yes | Range start | | date_to | string | Yes | Range end | | task_id | number | No | | | type | "activity" | "break" | No | | | archived / include_taskless | boolean | No | | | time_block_id | number | No | |

focus_create_time_entry

Creates a completed entry immediately. If task_id is set, uses the task-scoped endpoint; otherwise creates a taskless entry. type defaults to "activity".

| Arg | Type | Description | | --- | --- | --- | | task_id / project_id | number | | | description | string | | | start | string | RFC3339 | | duration | number | Seconds | | billable | boolean | | | tag_ids | number[] | | | time_block_id | number | | | type | "activity" | "break" | |

focus_update_time_entry

Partial update. Requires time_entry_id. Optional task_id selects the task-scoped path.

focus_delete_time_entry

Deletes immediately. Requires time_entry_id. Optional task_id for the task-scoped path.

Clients

focus_list_clients

Optional name filter plus pagination.

focus_create_client

Requires name. Optional currency (ISO 4217).

Tags

focus_list_tags

Optional name, tag_id (array), pagination.

focus_create_tag

Requires name and color (hex or Focus color token).

Statuses & search

focus_list_statuses

List task statuses. Optional name, type, pagination.

focus_search

Unified search across time entries, tasks, and projects.

| Arg | Type | Required | Description | | --- | --- | --- | --- | | keyword | string | Yes | Search text | | per_group | number | No | Results per group | | project_id / task_id | number | No | Scope | | only_me / include_drafts | boolean | No | |

Behavior notes

• Mutations are immediate — create / update / delete / start / stop have no confirmation step.
• Project tags on create — some Focus plans/roles reject tag_ids on POST. The tool creates the project first, then PATCHes tags; on failure you still get the project plus a warning.
• Workspace context — session cookie endpoints are not used; set org + workspace env vars.
• Quota — Focus enforces per-user-per-org hourly limits (e.g. Free ~30/hour). HTTP 402 means quota exhausted; wait for X-Toggl-Quota-Resets-In. Prefer env IDs so tools do not rediscover context every call.

Development

git clone https://github.com/copperline-ai/toggl-focus-mcp.git
cd toggl-focus-mcp
npm install
npm run check          # typecheck + unit/mocked MCP tests + build (CI gate)
npm run test:live      # optional — real Focus API; local only, needs .env
node dist/index.js

npm run check is the same gate used by GitHub Actions on PRs and before publish. It uses mocked Focus responses — CI never calls your real Toggl account.

Live MCP tests (local only)

Optional suite against a real Focus workspace. Not run in CI.

1. Copy .env.example → .env and set your Focus key + org/workspace IDs
2. Run:

npm run test:live

Reuses stable fixtures (client Toggl Focus, project Toggl Focus MCP, task MCP live test, tag MCP live). Disposable time entries are deleted. Paces ~1 req/sec for rate limits. .env is gitignored and not published.

Publishing

Releases use release-it + AI Gateway (semver bump, changelog, GitHub Release, npm publish):

npm run release:dry-run
npm pack --dry-run

CI secrets: NPM_ACCESS_TOKEN, AI_GATEWAY_API_KEY.

Vendored OpenAPI: openapi/focus.json from Focus OpenAPI.

Related

• Focus docs: engineering.toggl.com/docs/focus
• Focus auth: Bearer API keys
• Official OAuth MCP: @togglhq/mcp

License

MIT