Skip to main content
Glama

MCP Toggl Server

by verygoodplugins
OverviewInspectNewSchemaRelated ServersScore
TypeScript
Remote
3
1

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

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

  1. Get your Toggl API key from: https://track.toggl.com/profile

  2. 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)

  1. 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:

  1. First Run: Warms cache by fetching workspaces, projects, and clients

  2. Subsequent Calls: Uses cached names for hydration (95%+ cache hit rate)

  3. Smart Invalidation: TTL-based expiry with configurable duration

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

Deploy Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

Related Resources

Tools

View all tools

Related MCP Servers

  • 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
    • Apple

  • 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
    3
    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

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/verygoodplugins/mcp-toggl'

If you have feedback or need assistance with the MCP directory API, please join our Discord server