{"id":40639833,"url":"https://github.com/verygoodplugins/mcp-toggl","last_synced_at":"2026-05-01T07:03:05.757Z","repository":{"id":312638083,"uuid":"1048155658","full_name":"verygoodplugins/mcp-toggl","owner":"verygoodplugins","description":"MCP server for Toggl Track integration with intelligent caching and reporting tools","archived":false,"fork":false,"pushed_at":"2026-04-28T06:52:23.000Z","size":73,"stargazers_count":12,"open_issues_count":10,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-28T07:29:42.376Z","etag":null,"topics":["automation","mcp","mcp-server","modelcontextprotocol","reporting","time-tracking","toggl","typescript"],"latest_commit_sha":null,"homepage":"https://verygoodplugins.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verygoodplugins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T02:41:20.000Z","updated_at":"2026-04-28T06:52:26.000Z","dependencies_parsed_at":"2025-09-01T04:40:01.382Z","dependency_job_id":"93527f94-b64f-4d6a-857c-24729d9e4d6a","html_url":"https://github.com/verygoodplugins/mcp-toggl","commit_stats":null,"previous_names":["verygoodplugins/mcp-toggl"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/verygoodplugins/mcp-toggl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-toggl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-toggl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-toggl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-toggl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verygoodplugins","download_url":"https://codeload.github.com/verygoodplugins/mcp-toggl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-toggl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32487743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","mcp","mcp-server","modelcontextprotocol","reporting","time-tracking","toggl","typescript"],"created_at":"2026-01-21T08:02:00.735Z","updated_at":"2026-05-01T07:03:05.742Z","avatar_url":"https://github.com/verygoodplugins.png","language":"TypeScript","funding_links":[],"categories":["Business \u0026 Commerce Mcp Servers"],"sub_categories":[],"readme":"# MCP Toggl\n\n\u003e Talk to your time tracking. Pull reports, start timers, inspect desktop activity, and turn raw Toggl data into useful recaps from Claude or any MCP-compatible client.\n\n[![npm](https://img.shields.io/npm/v/@verygoodplugins/mcp-toggl)](https://www.npmjs.com/package/@verygoodplugins/mcp-toggl)\n[![MCP](https://img.shields.io/badge/MCP-server-blueviolet)](https://modelcontextprotocol.io)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Toggl API](https://img.shields.io/badge/Toggl-API%20v9-red)](https://developers.track.toggl.com/docs/)\n\n## See What Your Week Actually Looked Like\n\n\u003e You ask: \"Give me the recap of my week\"\n\nThe MCP server returns hydrated time entries with project, workspace, client, tag, and running-timer context. Your client can turn that into a readable recap:\n\n\u003e 32.7 hours across 31 entries and 7 projects. Monday was a light planning day, Tuesday had the long implementation block, Wednesday stayed focused on one project, and Friday turned into a shipping run. The top project took 27% of the week, with two smaller projects close behind.\n\n![Weekly recap chart](docs/images/weekly-recap.svg)\n\nThe server does not hard-code this prose or chart. It exposes structured Toggl data in a shape that makes synthesis easy.\n\n## Catch the Drift\n\n\u003e You ask: \"Did I actually work on what I said I worked on for that PR review entry?\"\n\n`toggl_get_timeline` can compare a tracked entry boundary with Toggl Track Desktop activity:\n\n\u003e The entry ran 1h 33m. About 67 minutes were in review tools, 5 minutes were scattered across chat apps, and the rest was idle or trimmed timeline space. The entry mostly checks out.\n\n![Drift detection chart](docs/images/drift-detection.svg)\n\nThis is useful before invoicing, after long context-switching days, or whenever a vague entry like \"admin\" starts hiding too much Slack and browser time.\n\n## See Patterns Over Time\n\n\u003e You ask: \"Show me last month at a glance\"\n\nDaily and weekly report tools make it straightforward for the client to render heatmaps, spot streaks, and surface intensity changes:\n\n![Monthly heatmap](docs/images/monthly-heatmap.svg)\n\nToggl is still the source of truth. The MCP layer makes the data easier for an agent to inspect, summarize, and visualize.\n\n## Things You Can Ask\n\n```text\nWhat am I currently tracking?\nHow much time did I spend on the website project this month?\nStart a timer for \"PR review\" on the Platform project\nShow me yesterday's hours as a chart\nWhat apps did I use most today?\nGenerate a daily report for last Friday\nCompare this week to last week by project\nWhich day this month had the most billable work?\n```\n\nChart prompts depend on your MCP client. The server returns the structured data; clients such as Claude decide how to render it.\n\n## What Makes This Useful\n\n**Hydrated responses**: time entries are enriched with `project_name`, `client_name`, `workspace_name`, `tag_names`, and normalized running-timer fields so the client does not need a second lookup for ordinary reporting.\n\n**Smart caching**: workspaces, projects, clients, tasks, and tags are cached after first read. `toggl_cache_stats` shows hits, misses, loaded entities, and hit rate.\n\n**Desktop activity timeline**: `toggl_get_timeline` summarizes app usage from Toggl Track Desktop and can return raw events when you need sequence analysis.\n\n**Privacy controls**: timeline calls support summary-only output with `include_events: false` and title redaction with `redact_titles: true`.\n\n**Period shortcuts**: `today`, `yesterday`, `week`, `lastWeek`, `month`, and `lastMonth` are supported on the tools where those periods make sense.\n\n**Recoverable errors**: workspace resolution errors include `available_workspaces`, and Toggl quota/rate-limit errors include structured retry hints.\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js `^20.19.0` or `\u003e=22.12.0`\n- A Toggl Track account\n- Your Toggl API token from [track.toggl.com/profile](https://track.toggl.com/profile)\n\n### Claude Desktop\n\nAdd this to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-toggl\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@verygoodplugins/mcp-toggl@latest\"],\n      \"env\": {\n        \"TOGGL_API_KEY\": \"your_api_key_here\",\n        \"TOGGL_DEFAULT_WORKSPACE_ID\": \"123456\"\n      }\n    }\n  }\n}\n```\n\n`TOGGL_DEFAULT_WORKSPACE_ID` is optional. If you have exactly one Toggl workspace, the server can resolve it automatically. If you have multiple workspaces and do not set a default, workspace-scoped tools return the available workspace IDs so the client can retry with `workspace_id`.\n\nRestart Claude Desktop, then ask:\n\n```text\nWhat am I currently tracking?\n```\n\n### Global Install\n\n```bash\nnpm install -g @verygoodplugins/mcp-toggl\nmcp-toggl --help\n```\n\n## Tools\n\n### Reports and Insights\n\n| Tool | What it does |\n| --- | --- |\n| `toggl_daily_report` | Hours by project and workspace for a date. Use `format: \"text\"` for display text or `\"json\"` for structured output. |\n| `toggl_weekly_report` | 7-day breakdown with daily totals and project rollups. Use `week_offset: -1` for last week. |\n| `toggl_get_time_entries` | Raw hydrated entries by period, date range, workspace, or project. |\n| `toggl_get_timeline` | Toggl Track Desktop app usage summary with optional raw events. |\n\n### Timer Control\n\n| Tool | What it does |\n| --- | --- |\n| `toggl_get_current_entry` | Returns the running timer, elapsed seconds, and hydrated project/workspace context. |\n| `toggl_start_timer` | Starts a timer with description, optional project/task, and tags. |\n| `toggl_stop_timer` | Stops the currently running timer. |\n\n### Lookups\n\n| Tool | What it does |\n| --- | --- |\n| `toggl_check_auth` | Verifies token access and lists available workspaces without exposing the token. |\n| `toggl_list_workspaces` | Lists all accessible workspaces. |\n| `toggl_list_projects` | Lists projects for a workspace using cache-backed reads after first fetch. |\n| `toggl_list_clients` | Lists clients for a workspace using cache-backed reads after first fetch. |\n\n### Cache Management\n\n| Tool | What it does |\n| --- | --- |\n| `toggl_warm_cache` | Pre-fetches workspace, project, client, and tag data before a heavy reporting session. |\n| `toggl_cache_stats` | Returns hits, misses, hit rate, loaded entity counts, and warm-cache state. |\n| `toggl_clear_cache` | Clears cached data. Useful after creating or renaming Toggl entities. |\n\n### Summaries\n\n| Tool | What it does |\n| --- | --- |\n| `toggl_project_summary` | Total hours per project for a period or date range. |\n| `toggl_workspace_summary` | Total hours per workspace for a period or date range. |\n\n## Timeline Privacy\n\nToggl Track Desktop activity can include window titles. Those titles may contain document names, email subjects, chat text, URLs, OAuth pages, or database names.\n\nSummary-only mode returns app totals without raw events:\n\n```json\n{\n  \"period\": \"today\",\n  \"include_events\": false\n}\n```\n\nEvents with redacted titles preserve sequence and duration but remove titles:\n\n```json\n{\n  \"period\": \"today\",\n  \"redact_titles\": true,\n  \"limit\": 50\n}\n```\n\nFull event mode is the default:\n\n```json\n{\n  \"period\": \"today\"\n}\n```\n\nWhen in doubt, use `include_events: false`.\n\n## Configuration Reference\n\n| Env var | Required | Default | Notes |\n| --- | --- | --- | --- |\n| `TOGGL_API_KEY` | Yes | - | Preferred env var for your Toggl API token. |\n| `TOGGL_API_TOKEN` | No | - | Supported alias for backwards compatibility. `TOGGL_API_KEY` is preferred. |\n| `TOGGL_TOKEN` | No | - | Supported alias for backwards compatibility. `TOGGL_API_KEY` is preferred. |\n| `TOGGL_DEFAULT_WORKSPACE_ID` | No | - | Used when a tool requires a workspace and none is passed. |\n| `TOGGL_CACHE_TTL` | No | `3600000` | Cache TTL in milliseconds. Default is 1 hour. |\n| `TOGGL_CACHE_SIZE` | No | `1000` | Maximum cached entity budget. |\n| `TOGGL_BATCH_SIZE` | No | `100` | Batch size used by API pagination helpers. |\n\n## Caveats\n\n**Toggl rate limits and quotas**: Toggl may return rate-limit or quota errors during chatty sessions. The server returns structured retry information when Toggl provides it. Warm the cache before large reporting sessions to avoid repeated project/client/tag fetches.\n\n**Running timer duration**: Toggl uses negative duration values for running entries. Read `running` and `elapsed_seconds` from the hydrated response instead.\n\n**Timeline availability**: `toggl_get_timeline` requires Toggl Track Desktop timeline sync. If it is not enabled or has not uploaded data yet, the tool returns `enabled: false` with setup guidance.\n\n**Timeline totals**: `limit` only limits returned raw events. `summary`, `total_seconds`, and `total_hours` are calculated from all matching events.\n\n## Local Development\n\n```bash\ngit clone https://github.com/verygoodplugins/mcp-toggl.git\ncd mcp-toggl\nnpm install\nnpm run build\nnpm test\n```\n\nUseful commands:\n\n```bash\nnpm run dev\nnpm run lint\nnpm run format\n```\n\n## License\n\nMIT.\n\nBuilt by [Very Good Plugins](https://verygoodplugins.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fmcp-toggl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverygoodplugins%2Fmcp-toggl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fmcp-toggl/lists"}