mcp-toggl

This MCP server provides Toggl Track integration for time tracking and reporting within MCP-enabled automation environments. It exposes a set of tools that let you start and stop timers, fetch current or past time entries, and generate both daily and weekly reports with useful breakdowns by project and workspace. The server uses an intelligent caching system to minimize API calls and accelerate hydration of time entries with project, workspace, and client names, making it well-suited for automated workflows in tools like Automation Hub. To use it, configure your MCP client to launch the server via npx and supply Toggl credentials (API key) and optional defaults for workspace and cache settings. Once running, you can invoke the provided tools from your automation scripts to pull structured JSON outputs that summarize activity, assist with billing, or generate progress reports.

Prerequisites:

• Node.js (recommended latest LTS) installed on your machine or hosting environment
• Access to the internet to fetch the MCP package from npm

Installation steps:

1. Ensure Node.js is installed. Verify with: node -v npm -v

2. Use npx to run the MCP Toggl server directly (no local clone required): npx @verygoodplugins/mcp-toggl@latest

3. Alternatively, if integrating into a runtime script or process manager, ensure your environment variables are set (see mcp_config example) and start the server via the chosen method (e.g., environment-managed startup script).

4. Prepare a .env file (optional but recommended for local testing): TOGGL_API_KEY=your_api_key_here TOGGL_DEFAULT_WORKSPACE_ID=123456 TOGGL_CACHE_TTL=3600000 TOGGL_CACHE_SIZE=1000

5. Add to your MCP configuration as shown in the mcp_config section, then restart the client to apply changes.

Tips and considerations:

• Use the recommended environment variable names: TOGGL_API_KEY, TOGGL_DEFAULT_WORKSPACE_ID, TOGGL_CACHE_TTL, and TOGGL_CACHE_SIZE.
• If you run into authentication issues, regenerate your Toggl API token from your Toggl Track profile and update the API key accordingly.
• The server supports cache warm-up and smart invalidation; adjust TOGGL_CACHE_TTL to balance freshness and API usage for your setup.
• For Claude Desktop or Cursor integrations shown in the README, point the command and path settings to the running npx invocation or to the built server file when applicable.
• The toolset includes time tracking, reporting (daily/weekly), and management commands like listing workspaces/projects/clients, as well as cache management commands.
• Security: avoid committing real API keys; use placeholders like your_api_key_here in documentation and config samples.