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

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

# 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

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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables time tracking and reporting through Toggl Track integration with intelligent caching. Supports starting/stopping timers, generating daily/weekly reports, and managing projects with structured JSON output for automation workflows.

Related MCP Servers

Harvest Natural Language Time Entry MCP Server
adrian-dotco
A
security
A
license
A
quality
Enables natural language time tracking and reporting for Harvest, including automatic leave requests, project/task matching, and date parsing.
Last updated -
0
3
MIT License
Harvest MCP Server
taiste
A
security
A
license
A
quality
Integrates with Harvest time tracking API, enabling AI assistants to manage time entries, projects, clients, and tasks through natural language commands.
Last updated -
11
15
MIT License
Clockify MCP Server
ratheesh-aot
A
security
A
license
A
quality
Provides comprehensive integration with the Clockify time tracking API, enabling automated time entry management, project organization, task tracking, and reporting through a standardized interface.
Last updated -
29
1
1
MIT License
TimeCamp MCP Serverofficial
timecamp-org
-
security
F
license
-
quality
A Model Context Protocol server that provides time tracking integration with TimeCamp, allowing AI assistants to create, retrieve, update, and delete time entries through natural language commands.
Last updated -

View all related MCP servers

MCP Toggl Server

Features

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