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