toggl-focus-mcp
Enables interaction with Toggl Focus (2.0) API, providing tools to manage projects, tasks, time entries, and timers within a workspace.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@toggl-focus-mcp Start a timer on project Website Redesign"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpAuth | Focus Bearer API key ( |
API |
|
Transport | stdio MCP |
Node | ≥ 20 (CI / |
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
A Toggl Focus / 2.0 API key (
toggl_sk_…) — shown once when createdYour organization ID and workspace ID (strongly recommended)
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.
Related MCP server: timing-mcp-server
Environment variables
Variable | Required | Description |
| Yes* | Focus API key ( |
| Yes* | Alias for the Focus API key |
| Yes* | Additional alias |
| Recommended | Default organization ID |
| Recommended | Default workspace ID |
| No | API base (default |
* 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-mcpVerify:
claude mcp listClaude Desktop
Edit claude_desktop_config.json, then restart Claude Desktop.
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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-mcpOr 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 |
| number | Overrides |
| number | Overrides |
| number | Default |
| number | Default |
Account & context
focus_whoami
Account metadata + user settings for the authenticated Focus key.
Arg | Type | Required | Description |
| boolean | No | Default |
| 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 |
| string | No | Search name/email |
| string | No | Active-status filter when supported |
| number | No | Pagination |
Projects
focus_list_projects
List workspace projects.
Arg | Type | Description |
| string | Filter by project or client name |
| boolean | Status filters |
| number[] | Filter by client IDs |
| number[] | Filter by tag IDs |
focus_get_project
Arg | Type | Required |
| number | Yes |
focus_create_project
Creates immediately. Requires name.
Arg | Type | Description |
| string | Required |
| string | |
| number | Supported on create |
| string | |
| boolean | |
| string |
|
| number[] | Applied via follow-up PATCH; may be forbidden on some plans/roles — project still creates and a |
| 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 |
| string | Name filter |
| number[] | Project IDs |
| number[] | Status IDs |
| number[] | Assignees |
| number[] | Tags |
| boolean | |
| number[] | Parent tasks |
| boolean | Expand assignees |
focus_get_task
Requires task_id. Optional include_assignees.
focus_create_task
Creates immediately. Requires name.
Arg | Type | Description |
| string | Required |
| string | |
| number | |
| number[] | |
| number | |
|
| |
| boolean | |
| string |
|
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 |
|
| Default |
| number | |
| string | |
| boolean | |
| number[] | |
| number | |
| 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 |
| string | Yes | Range start |
| string | Yes | Range end |
| number | No | |
|
| No | |
| boolean | No | |
| 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 |
| number | |
| string | |
| string | RFC3339 |
| number | Seconds |
| boolean | |
| number[] | |
| number | |
|
|
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 |
| string | Yes | Search text |
| number | No | Results per group |
| number | No | Scope |
| 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_idsonPOST. The tool creates the project first, then PATCHes tags; on failure you still get the project plus awarning.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.jsnpm 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.
Copy
.env.example→.envand set your Focus key + org/workspace IDsRun:
npm run test:liveReuses 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-runCI 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
Available Tools
24 toolsfocus_create_clientC
Toggl Focus/2.0: create a client immediately. Requires name.
Inputs: name (required), currency, workspace_id, organization_id.
focus_create_projectA
Toggl Focus/2.0: create a project immediately (no confirmation). Requires name. Optional client_id is supported. tag_ids are applied in a follow-up PATCH when permitted by the workspace plan/role; if tags are forbidden the project is still created and a warning is returned.
Inputs: name (required), color, pinned, private, +9 more.
focus_create_tagB
Toggl Focus/2.0: create a tag immediately. Requires name and color.
Inputs: name (required), color (required), workspace_id, organization_id.
focus_create_taskA
Toggl Focus/2.0: create a task immediately (no confirmation). Requires name.
Inputs: name (required), notes, pinned, private, +13 more.
focus_create_time_entryA
Toggl Focus/2.0: create a completed time entry immediately. If task_id is set, creates under that task; otherwise creates a taskless entry. type defaults to activity.
Inputs: type, start, tag_ids, task_id, +7 more.
focus_delete_time_entryA
Toggl Focus/2.0: delete a time entry immediately (no confirmation).
Inputs: time_entry_id (required), task_id, workspace_id, organization_id.
focus_get_current_timerB
Toggl Focus/2.0: get the currently running timer for the workspace, if any.
Inputs: workspace_id, organization_id.
focus_get_projectB
Toggl Focus/2.0: get a project by ID.
Inputs: project_id (required), workspace_id, organization_id.
focus_get_taskB
Toggl Focus/2.0: get a task by ID.
Inputs: task_id (required), workspace_id, organization_id, include_assignees.
focus_get_workspace_contextA
Toggl Focus/2.0: resolve organization_id and workspace_id from env/args (and current_workspace_id from settings when needed). Caches IDs for later tools. Set TOGGL_ORGANIZATION_ID + TOGGL_WORKSPACE_ID. Note: the session /workspaces/{id}/context endpoint is not used with API keys.
Inputs: workspace_id, organization_id.
focus_list_clientsB
Toggl Focus/2.0: list clients in a workspace.
Inputs: name, page, per_page, workspace_id, +1 more.
focus_list_org_usersA
Toggl Focus/2.0: list organization users (for assignee resolution). Mutations are not performed.
Inputs: page, filter, per_page, workspace_id, +2 more.
focus_list_projectsB
Toggl Focus/2.0: list projects in a workspace. Not Track.
Inputs: name, page, pinned, tag_id, +6 more.
focus_list_statusesA
Toggl Focus/2.0: list task statuses for a workspace.
Inputs: name, page, type, per_page, +2 more.
focus_list_tagsB
Toggl Focus/2.0: list tags in a workspace.
Inputs: name, page, tag_id, per_page, +2 more.
focus_list_tasksB
Toggl Focus/2.0: list tasks with common filters (project, status, assignee, name, pinned). Not Track.
Inputs: name, page, pinned, tag_id, +9 more.
focus_list_time_entriesA
Toggl Focus/2.0: list time entries in a date range (date_from/date_to required). Accepts YYYY-MM-DD or RFC3339.
Inputs: date_to (required), date_from (required), page, type, +7 more.
focus_searchB
Toggl Focus/2.0: unified search across time entries, tasks, and projects.
Inputs: keyword (required), only_me, task_id, per_group, +4 more.
focus_start_timerC
Toggl Focus/2.0: start a timer immediately. type defaults to activity. Optional task_id/project_id/description.
Inputs: type, start, tag_ids, task_id, +6 more.
focus_stop_timerA
Toggl Focus/2.0: stop the running timer. end defaults to now (UTC) if omitted.
Inputs: end, workspace_id, organization_id.
focus_update_projectB
Toggl Focus/2.0: partially update a project (PATCH). Changes apply immediately.
Inputs: project_id (required), name, color, pinned, +10 more.
focus_update_taskA
Toggl Focus/2.0: partially update a task (PATCH). Changes apply immediately.
Inputs: task_id (required), name, notes, pinned, +13 more.
focus_update_time_entryC
Toggl Focus/2.0: partially update a time entry (PATCH). Changes apply immediately.
Inputs: time_entry_id (required), type, start, tag_ids, +7 more.
focus_whoamiA
Toggl Focus/2.0: return account metadata and user settings for the authenticated Focus API key. Not Track.
Inputs: workspace_id, organization_id, include_settings.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool targets a distinct resource and action (e.g., get_current_timer vs. list_time_entries, start_timer vs. create_time_entry). Even with overlapping domains, the descriptions make boundaries clear.
All tools share the 'focus_' prefix and almost all follow a verb_noun pattern (list_projects, create_task, update_time_entry). The few exceptions (whoami, search) are standard single-word commands and don't break the overall consistency.
24 tools is on the higher end but justified by the broad Toggl Focus domain covering projects, tasks, time entries, clients, tags, statuses, and user/context helpers. It feels comprehensive without redundant or trivial tools.
Core resources have strong coverage: projects and tasks support list/get/create/update, and time entries support list/create/update/delete. However, projects and tasks lack delete operations, and clients/tags only support list/create, leaving notable lifecycle gaps for these resources.
Maintenance
Related MCP Connectors
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
timesheet.io MCP server - manage timers, projects, tasks and reports
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
MCP server for Google Tasks: review, plan and tidy your tasks by asking. Deletes always ask first.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for Productive.io that enables users to log time, inspect projects, and manage time entries using natural language commands. It features fuzzy project matching, local caching, and remembers default services per project for streamlined time tracking.14MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI assistants to interact with the Timing application for managing time tracking and tasks, including project and time entry operations.7MIT
- AlicenseNot gradedqualityCmaintenanceEnables to manage Toggl time entries, projects, tasks, and timers through natural language commands.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets LLMs interact with your Clockify workspace for time-tracking automation and reporting, enabling natural language logging of time entries, querying entries, and generating reports.MIT