MCP Toggl Server

The MCP Toggl Server lets you manage Toggl Track time tracking and reporting directly from your automation or personal workflow clients. It provides timer control, hydrated time entries, and smart caching to keep responses fast and efficient.

How to use

You interact with the Toggl MCP through your MCP client (for example Claude Desktop or Cursor). Install or run the MCP via a package runner, then configure the environment to provide Toggl credentials and caching preferences. Use the available actions to start and stop timers, fetch current or past time entries, and generate daily or weekly reports with project and workspace breakdowns. Hydration enriches time entries with project, workspace, and client names for clearer context. The server is designed to work smoothly with Automation Hub workflows by returning structured JSON.

Key actions you can perform include starting timers, stopping the active timer, retrieving time entries with optional filters, and generating summarized reports by day, week, or project. When you use the caching features, most requests are served from memory, reducing the number of API calls to Toggl and speeding up responses. If you need to pre-load data, you can warm the cache to fetch workspaces, projects, and clients upfront.

How to install

Prerrequisites: you need Node.js installed on your machine.

# Install dependencies and prepare the server for production use
npm install
npm run build

If you prefer to run via an MCP client without cloning or building locally, you can use an MCP runtime command shown in the examples below.

# Start the MCP server via npx (example usage)
npx @verygoodplugins/mcp-toggl@latest

Configuration

Get your Toggl API key from: Toggl Track profile page. Create a local environment file or set environment variables in your MCP client configuration.

Environment variables you can use (placeholders shown):

TOGGL_API_KEY=your_api_key_here

# Aliases also supported (only use one if needed):
# TOGGL_API_TOKEN=your_api_key_here
# TOGGL_TOKEN=your_api_key_here

# Optional configuration
TOGGL_DEFAULT_WORKSPACE_ID=123456  # Your default workspace
TOGGL_CACHE_TTL=3600000            # Cache TTL in ms (default: 1 hour)
TOGGL_CACHE_SIZE=1000              # Max cached entities (default: 1000)

Security and credentials

This server uses a Toggl API token for authentication. Treat API keys as secrets and avoid committing them to version control. Use placeholders like your_api_key_here in examples. If you regenerate a token, update your MCP client configuration and restart the server.

Troubleshooting

If you run into authentication issues, verify that your Toggl API key is correct and that the key is configured in the environment variables used by your MCP client. If the server reports 401/403, regenerate the token and update your config. For stale data, run the cache clear operation or increase the TTL to suit your needs. Exponential backoff will be used for rate-limited requests.

Notes

The MCP Toggl Server is designed for automation-friendly workflows. It provides structured JSON output suitable forAutomation Hub and similar tools, enabling easy integration into larger automation pipelines.

Available tools

toggl_get_time_entries

Fetch time entries with optional filters such as period, workspace_id, and project_id.

toggl_get_current_entry

Retrieve the currently running timer entry.

toggl_start_timer

Start a new timer with details like description, project, and tags.

toggl_stop_timer

Stop the currently running timer.

toggl_daily_report

Generate a daily report with project/workspace breakdowns.

toggl_weekly_report

Generate a weekly report with daily breakdowns.

toggl_project_summary

Get total hours per project for a date range.

toggl_workspace_summary

Get total hours per workspace.

toggl_list_workspaces

List all available workspaces.

toggl_list_projects

List projects in a workspace.

toggl_list_clients

List clients in a workspace.

toggl_warm_cache

Pre-fetch workspace/project/client data for better performance.

toggl_cache_stats

View cache performance metrics.

toggl_clear_cache

Clear all cached data.