# mcp-toggl [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/verygoodplugins/mcp-toggl  
**GitHub Stars:** 36  
**npm Downloads (last month):** 799  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-toggl

## Description
MCP server for Toggl Track integration with intelligent caching and reporting tools

## Tools
Capabilities this server exposes over MCP:

- **toggl_check_auth** — Verify Toggl API connectivity and authentication is valid
- **toggl_get_time_entries** — Get time entries with optional date range filters. Returns hydrated entries with project/workspace names.
- **toggl_get_current_entry** — Get the currently running time entry, if any
- **toggl_start_timer** — Start a new time entry timer
- **toggl_stop_timer** — Stop the currently running timer
- **toggl_daily_report** — Generate a daily report with hours by project and workspace
- **toggl_weekly_report** — Generate a weekly report with daily breakdown and project summaries
- **toggl_project_summary** — Get total hours per project for a date range
- **toggl_workspace_summary** — Get total hours per workspace for a date range
- **toggl_list_workspaces** — List all available workspaces
- **toggl_list_projects** — List projects for a workspace
- **toggl_list_clients** — List clients for a workspace
- **toggl_warm_cache** — Pre-fetch and cache workspace, project, client, and tag data for better performance
- **toggl_cache_stats** — Get cache statistics and performance metrics
- **toggl_clear_cache** — Clear all cached data
- **toggl_get_timeline** — Get Toggl Desktop activity timeline showing application usage. PRIVACY NOTE: raw events include window titles that may contain sensitive document names, email subjects, chat text, URLs, OAuth pages, or database names; use include_events: false for privacy-conscious summary-only usage. Requires Toggl Track Desktop timeline sync to be enabled. Response semantics: summary is { [appName: string]: total_seconds }; total_events is the post-filter event count; returned_events is the returned events array length; truncated means only the events array was limited, never the summary. limit does not affect summary calculation. total_seconds is canonical; total_hours is rounded to 4 decimals for display.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-toggl": {
    "command": "npx",
    "args": ["-y","@verygoodplugins/mcp-toggl@latest"],
    "env": {
      "TOGGL_API_KEY": "",
      "TOGGL_API_TOKEN": "",
      "TOGGL_TOKEN": "",
      "TOGGL_DEFAULT_WORKSPACE_ID": "",
      "TOGGL_CACHE_TTL": "",
      "TOGGL_CACHE_SIZE": "",
      "TOGGL_BATCH_SIZE": ""
    }
  }
}
```

**Requires environment variables:** `TOGGL_API_KEY`, `TOGGL_API_TOKEN`, `TOGGL_TOKEN`, `TOGGL_DEFAULT_WORKSPACE_ID`, `TOGGL_CACHE_TTL`, `TOGGL_CACHE_SIZE`, `TOGGL_BATCH_SIZE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mcp-toggl MCP server does

The mcp-toggl MCP server exposes Toggl Track data and actions to an MCP client. It is intended for time tracking, reporting, and work-pattern analysis within the Workplace & Productivity category. Reports can include project, workspace, client, tag, and running-timer context, reducing the need for separate lookups before an agent summarizes results.

The server supports daily and weekly reports, date-range queries, project and workspace totals, current timer inspection, timer creation and stopping, and workspace or project discovery. It can also read Toggl Track Desktop activity when timeline synchronization is enabled.

## How it works

The server communicates with Toggl Track through the Toggl API and returns structured data for the connected MCP client to interpret or render. Reporting tools support shortcuts such as `today`, `yesterday`, `week`, `lastWeek`, `month`, and `lastMonth` where applicable. Weekly reports can also use a week offset, such as `-1` for the previous week.

Entity lookups use an in-memory cache for workspaces, projects, clients, tasks, and tags. Cache tools allow an agent to preload data, inspect hit and miss statistics, or clear entries after Toggl entities change. The server also returns structured information for workspace-resolution and rate-limit errors when available.

## Setup and configuration

Install and run the package with Node.js `^20.19.0` or `>=22.12.0`. A Toggl Track account and API token are required. For Claude Desktop, configure the server with `npx -y @verygoodplugins/mcp-toggl@latest`, then provide `TOGGL_API_KEY` in the environment. `TOGGL_DEFAULT_WORKSPACE_ID` is optional; it avoids ambiguity when an account has multiple workspaces. With one accessible workspace, the server can resolve it automatically.

The server also accepts `TOGGL_API_TOKEN` and `TOGGL_TOKEN` as token aliases. `TOGGL_CACHE_TTL`, `TOGGL_CACHE_SIZE`, and `TOGGL_BATCH_SIZE` control cache duration, entity capacity, and API pagination batch size. It can alternatively be installed globally with npm and started using the `mcp-toggl` command.

## Tools and capabilities

The mcp-toggl MCP server includes these tool groups:

- Reports: daily reports, weekly reports, hydrated time entries, project summaries, and workspace summaries.
- Timer control: read the active entry, start a timer with a description and optional project or tags, and stop the active timer.
- Lookups: check authentication, list workspaces, list projects, and list clients.
- Cache management: warm, inspect, and clear cached entity data.
- Timeline analysis: summarize Toggl Track Desktop application usage and optionally return raw activity events.

Timeline requests can omit raw events with `include_events: false` or redact window titles with `redact_titles: true`. This matters because titles may contain document names, email subjects, chat content, URLs, or database names.

## Limitations and notes

The mcp-toggl MCP server cannot provide desktop activity unless Toggl Track Desktop timeline synchronization is enabled and data has uploaded. Timeline `limit` restricts returned raw events, not the totals calculated across matching events. Running Toggl entries use negative duration values, so clients should use the hydrated `running` and `elapsed_seconds` fields instead.

Toggl rate limits and quotas may affect chatty sessions. Warming the cache can reduce repeated entity requests, but it does not remove Toggl service limits. After creating or renaming entities, clear the cache before relying on refreshed lookup results. The project is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/mcp-toggl/readme_