Skip to content
English
Go to Toggl 2.0
  • There are no suggestions because the search field is empty.

Toggl 2.0 MCP and CL

Connect Toggl 2.0 to AI assistants like Codex, Claude Desktop, and Cursor — or use the CLI from your terminal — to manage tasks, projects, and time without leaving your workflow.

Toggl 2.0 offers two tools for working with your data outside the web app:

  • MCP server (@togglhq/mcp) — connects AI assistants to Toggl 2.0 via the Model Context Protocol
  • CLI (@togglhq/cli) — a terminal interface for the same Toggl 2.0 API

Both tools work with Toggl 2.0 workspaces on production.

Overview

The MCP server lets an AI assistant read and update your Toggl 2.0 data — tasks, projects, time entries, time blocks, reports, and more — through natural conversation. The first time you use it, your AI assistant prompts you to sign in with your Toggl account and opens a browser window to complete sign-in.

The CLI exposes the same capabilities from a terminal, which is useful for scripts, automation, and developers who prefer command-line workflows.

Install the MCP server

Recommended (no global install):


{
  "mcpServers": {
    "toggl-focus": {
      "command": "npx",
      "args": ["-y", "@togglhq/mcp"]
    }
  }
}

Add this to your MCP client's config (for example Codex MCP settings, Cursor MCP settings, or Claude Desktop's claude_desktop_config.json).

A one-click install link for Cursor is also available on the @togglhq/mcp npm page.

Once installed, start using Toggl through your AI assistant — for example, ask it to list your tasks or log time. On first use, your assistant prompts you to sign in and opens your browser to complete it.

Install the CLI

npm install -g @togglhq/cli

Or run without installing:

npx @togglhq/cli

Authenticate once:

toggl auth

This opens your browser for OAuth sign-in and saves your session locally.

Authentication and workspaces

MCP: The first time you ask your AI assistant to do something with Toggl, it prompts you to sign in and opens your browser. After that, your session is saved locally and refreshes automatically. Sign in again only if you need to switch workspaces or after a long period of inactivity (about 4 weeks).

CLI: Run toggl auth once to sign in. Use toggl profile commands to switch between saved accounts or workspaces.

What you can do

Through MCP or CLI you can work with Toggl 2.0 data including:

  • Tasks — list, create, update, delete
  • Projects — list, create, update, archive
  • Time entries — list, start, stop, create, update
  • Time blocks — planned calendar time
  • Reports — query report data
  • Organization — workspaces, members, invitations (based on your role)

Supported AI clients

The MCP server works with any MCP-compatible client, including:

  • Codex — add from MCP settings in the Codex app (Settings → MCP servers → Add server)
  • Cursor — add via MCP settings or the Cursor Directory listing
  • Claude Desktop — add to claude_desktop_config.json

The server is also listed in the official MCP Registry.

CLI basics


# See your projects
toggl projects list

# Create a task
toggl tasks create --data '{"name": "Write weekly report", "project_id": 123456}'

# Start and stop a timer
toggl time-entries start --task-id 12345
toggl time-entries stop

# See planned time on your calendar
toggl time-blocks list --date-from 2026-07-01 --date-to 2026-07-07

# List workspace members
toggl users list

 

Use toggl --help and toggl <command> --help to explore available commands. Add --json for machine-readable output.

To install the agent skill for coding assistants:

toggl skill setup

Plan availability and limits

There is no separate cap on MCP or CLI requests. Access follows your Toggl 2.0 subscription:

Plan Access
Free Core features available on the Free plan. Paid-only features (for example Premium reports or advanced capabilities) are not available.
Free — reports Report data requests are limited to 30 per month, same as in the web app.
Starter Everything included on Starter. Premium-only features are not available.
Premium / Enterprise Full access to features included on your plan.

In practice:

  • If you can do something in the Toggl 2.0 web app on your plan, you can do it through MCP or CLI.
  • If a feature is locked or limited in the web app, it is locked or limited through MCP and CLI too.
  • MCP and CLI do not bypass plan restrictions.

Troubleshooting

The MCP server doesn't respond / sign-in fails

Ask your AI assistant to sign in to Toggl. It will open your browser to complete sign-in. If that doesn't work, restart your AI client and try again.

I get "feature not available" or permission errors

Your plan or role doesn't include that feature — same as in the web app. Upgrade your plan or ask a workspace admin if you need access.

Report queries stop working on the Free plan

Free plans are limited to 30 report data requests per month. This applies in the web app, MCP, and CLI. Wait until the next month or upgrade for higher limits.