What can you do with this server?

A Model Context Protocol server that integrates with Toggl Track to provide comprehensive time tracking, reporting, and workspace management with intelligent caching. Time Tracking: Start/stop timers with descriptions, projects, tags, and tasks. View currently running timers and query historical entries with flexible filtering by date ranges (today, yesterday, week, month, or custom dates), workspaces, and projects. All entries are automatically enriched with full project, workspace, and client names. Reporting & Analytics: Generate daily reports with project and workspace breakdowns, weekly summaries with daily and project totals, project-specific summaries, and workspace summaries. Reports are available in JSON (for automation) or formatted text (for readability). Workspace Management: List and retrieve details for workspaces, projects, and clients to organize and browse your Toggl data. Performance Optimization: Intelligent caching system with configurable TTL (default 1 hour), LRU eviction (keeping memory under 10MB), cache warming for pre-fetching data, cache statistics monitoring, and manual cache clearing. Authentication & Reliability: Verify API connectivity and validate credentials. Automatic retry with exponential backoff for rate limiting. Supports multiple environment variables (TOGGL_API_KEY, TOGGL_API_TOKEN, or TOGGL_TOKEN) with Basic auth using API tokens. Integration Features: Structured JSON output optimized for automation platforms like Automation Hub, with flexible date ranges and optional filtering by workspace or project to retrieve exactly the data you need.

Which integrations are available for this server?

Provides comprehensive time tracking and reporting capabilities including starting/stopping timers, retrieving time entries, generating daily/weekly reports with project breakdowns, and managing workspaces, projects, and clients through the Toggl Track API.

How do I use MCP Toggl Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Toggl Server show me my time entries for today" 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.

MCP Toggl Server

A Model Context Protocol (MCP) server for Toggl Track integration, providing time tracking and reporting capabilities with intelligent caching for optimal performance.

Features

Time Tracking: Start/stop timers, get current and past time entries
Smart Reporting: Daily/weekly reports with project and workspace breakdowns
Performance Optimized: Intelligent caching system minimizes API calls
Data Hydration: Automatically enriches time entries with project/workspace/client names
Flexible Filtering: Query by date ranges, workspaces, or projects
Automation Ready: Structured JSON output perfect for Automation Hub workflows

Related MCP server: Harvest MCP Server

Quick Start (Recommended)

Use via npx without cloning or building locally.

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "mcp-toggl": { "command": "npx @verygoodplugins/mcp-toggl@latest", "env": { "TOGGL_API_KEY": "your_api_key_here", "TOGGL_DEFAULT_WORKSPACE_ID": "123456", "TOGGL_CACHE_TTL": "3600000", "TOGGL_CACHE_SIZE": "1000" } } } }

Cursor

Add this to your Cursor MCP settings (e.g., ~/.cursor/mcp.json):

{ "mcp": { "servers": { "mcp-toggl": { "command": "npx", "args": ["@verygoodplugins/mcp-toggl@latest"], "env": { "TOGGL_API_KEY": "your_api_key_here", "TOGGL_DEFAULT_WORKSPACE_ID": "123456", "TOGGL_CACHE_TTL": "3600000", "TOGGL_CACHE_SIZE": "1000" } } } } }

Manual Installation

npm install npm run build

Configuration

Get your Toggl API key from: https://track.toggl.com/profile
Create a .env file:

TOGGL_API_KEY=your_api_key_here # Aliases also supported (use one of these only 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)

Add to your MCP configuration:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "mcp-toggl": { "command": "node", "args": ["/path/to/mcp-toggl/dist/index.js"], "env": { "TOGGL_API_KEY": "your_api_key_here" } } } }

Cursor

Edit .mcp.json in your project:

{ "mcpServers": { "mcp-toggl": { "command": "node", "args": ["./mcp-servers/mcp-toggl/dist/index.js"], "env": { "TOGGL_API_KEY": "your_api_key_here" } } } }

Available Tools

Time Tracking

`toggl_get_time_entries`

Get time entries with optional filters.

{ "period": "today", // or: yesterday, week, lastWeek, month, lastMonth "workspace_id": 123456, "project_id": 789012 }

`toggl_get_current_entry`

Get the currently running timer.

`toggl_start_timer`

Start a new time entry.

{ "description": "Working on MCP server", "project_id": 123456, "tags": ["development", "mcp"] }

`toggl_stop_timer`

Stop the currently running timer.

Reporting

`toggl_daily_report`

Generate a daily report with project/workspace breakdowns.

{ "date": "2024-09-01", "format": "json" // or "text" for formatted output }

`toggl_weekly_report`

Generate a weekly report with daily breakdowns.

{ "week_offset": 0, // 0 = this week, -1 = last week "format": "json" }

`toggl_project_summary`

Get total hours per project for a date range.

{ "period": "month", "workspace_id": 123456 }

`toggl_workspace_summary`

Get total hours per workspace.

Management

`toggl_list_workspaces`

List all available workspaces.

`toggl_list_projects`

List projects in a workspace.

{ "workspace_id": 123456 }

`toggl_list_clients`

List clients in a workspace.

Cache Management

`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.

Performance Optimization

The server uses an intelligent caching system to minimize API calls:

First Run: Warms cache by fetching workspaces, projects, and clients
Subsequent Calls: Uses cached names for hydration (95%+ cache hit rate)
Smart Invalidation: TTL-based expiry with configurable duration
Memory Efficient: LRU eviction keeps memory usage under 10MB

Typical Performance

First report: 2-3 API calls (warm cache + get entries)
Subsequent reports: 1 API call (just time entries)
Cache hit rate: >95% for typical usage

Usage Examples

Daily Standup Report

// Get today's time entries with full details toggl_daily_report({ "format": "text" })

Weekly Summary for Automation Hub

// Get last week's data as JSON toggl_weekly_report({ "week_offset": -1 })

Project Hours Tracking

// Get this month's hours by project toggl_project_summary({ "period": "month" })

Integration with Automation Hub

The server returns structured JSON perfect for Automation Hub workflows:

// Example daily report output { "date": "2024-09-01", "total_hours": 8.5, "by_project": [ { "project_name": "MCP Development", "client_name": "Internal", "total_hours": 4.5, "billable_hours": 0 } ], "by_workspace": [ { "workspace_name": "Very Good Plugins", "total_hours": 8.5, "project_count": 3 } ] }

Troubleshooting

API Key Issues

Ensure your API key is correct (get from https://track.toggl.com/profile)
API key goes in the username field, "api_token" as password for basic auth
Trim whitespace: copy/paste can include trailing spaces/newlines which cause 401/403
Accepted env var names: TOGGL_API_KEY (preferred), TOGGL_API_TOKEN, or TOGGL_TOKEN
If you see 401/403, regenerate the token on your Toggl profile and update your MCP config

Security & Token Lifecycle

This server uses Basic Auth with a Toggl API token, not OAuth; there is no refresh token to manage.
Toggl API tokens do not expire automatically. They only change if you manually regenerate them or if Toggl invalidates them during a security event.
If you regenerate your token, the old one stops working immediately. Update the TOGGL_API_KEY in your Claude/Cursor config and restart the client.
Never commit real secrets to version control. Use placeholders like your_api_key_here in docs and examples.
Claude Desktop stores the env value in claude_desktop_config.json on your machine. Treat that file as sensitive and do not share it.

Quick Auth Check

You can verify connectivity by calling the toggl_check_auth tool, which pings /me and lists your available workspaces without exposing your token.

Rate Limiting

The server implements automatic retry with exponential backoff
Respects Toggl's rate limits (max 1 request per second)

Cache Issues

Run toggl_clear_cache if data seems stale
Adjust TOGGL_CACHE_TTL for your needs (default: 1 hour)

Development

# Run in development mode npm run dev # Build for production npm run build # Test the server npm test

License

GPL-3.0

Support

For issues or questions, please open an issue on GitHub.

Built with 🧡 for the open source community by Very Good Plugins

MCP Toggl Server

Features

Quick Start (Recommended)

Claude Desktop

Cursor

Manual Installation

Configuration

Claude Desktop

Cursor

Available Tools

Time Tracking

toggl_get_time_entries

toggl_get_current_entry

toggl_start_timer

toggl_stop_timer

Reporting

toggl_daily_report

toggl_weekly_report

toggl_project_summary

toggl_workspace_summary

Management

toggl_list_workspaces

toggl_list_projects

toggl_list_clients

Cache Management

toggl_warm_cache

toggl_cache_stats

toggl_clear_cache

Performance Optimization

Typical Performance

Usage Examples

Daily Standup Report

Weekly Summary for Automation Hub

Project Hours Tracking

Integration with Automation Hub

Troubleshooting

API Key Issues

Security & Token Lifecycle

Quick Auth Check

Rate Limiting

Cache Issues

Development

License

Support

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

`toggl_get_time_entries`

`toggl_get_current_entry`

`toggl_start_timer`

`toggl_stop_timer`

`toggl_daily_report`

`toggl_weekly_report`

`toggl_project_summary`

`toggl_workspace_summary`

`toggl_list_workspaces`

`toggl_list_projects`

`toggl_list_clients`

`toggl_warm_cache`

`toggl_cache_stats`

`toggl_clear_cache`