m

mcp-toggl

IrisNyx/mcp-toggl
Hosted
0 Stars 32 次浏览 更新于 2026-08-23

MCP Toggl 是一个工具，允许您与 Toggl 的时间跟踪数据进行交互。它可以提取报告、启动计时器、检查桌面活动，并将原始 Toggl 数据转换为有用的摘要。服务器以一种易于客户端合成和可视化信息的方式暴露结构化的 Toggl 数据。

开发者工具

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "mcp-toggl": {
      "args": [
        "-y",
        "@verygoodplugins/mcp-toggl@latest"
      ],
      "command": "npx",
      "env": {
        "TOGGL_API_KEY": "your_api_key_here",
        "TOGGL_DEFAULT_WORKSPACE_ID": "123456"
      }
    }
  }
}

该服务需要配置环境变量：TOGGL_API_KEY、TOGGL_DEFAULT_WORKSPACE_ID

可用工具 （16 个）

该服务在 MCP 协议中暴露的工具，AI 可按需调用

toggl_check_auth

Verify Toggl API connectivity and authentication is valid

该工具无需必填参数，直接调用即可

toggl_get_time_entries 5 个参数

Get time entries with optional date range filters. Returns hydrated entries with project/workspace names.

该工具无需必填参数，直接调用即可

toggl_get_current_entry

Get the currently running time entry, if any

该工具无需必填参数，直接调用即可

toggl_start_timer 5 个参数

Start a new time entry timer

该工具无需必填参数，直接调用即可

toggl_stop_timer

Stop the currently running timer

该工具无需必填参数，直接调用即可

toggl_daily_report 2 个参数

Generate a daily report with hours by project and workspace

该工具无需必填参数，直接调用即可

toggl_weekly_report 2 个参数

Generate a weekly report with daily breakdown and project summaries

该工具无需必填参数，直接调用即可

toggl_project_summary 4 个参数

Get total hours per project for a date range

该工具无需必填参数，直接调用即可

toggl_workspace_summary 3 个参数

Get total hours per workspace for a date range

该工具无需必填参数，直接调用即可

toggl_list_workspaces

List all available workspaces

该工具无需必填参数，直接调用即可

toggl_list_projects 1 个参数

List projects for a workspace

该工具无需必填参数，直接调用即可

toggl_list_clients 1 个参数

List clients for a workspace

该工具无需必填参数，直接调用即可

toggl_warm_cache 1 个参数

Pre-fetch and cache workspace, project, client, and tag data for better performance

该工具无需必填参数，直接调用即可

toggl_cache_stats

Get cache statistics and performance metrics

该工具无需必填参数，直接调用即可

toggl_clear_cache

Clear all cached data

该工具无需必填参数，直接调用即可

toggl_get_timeline 7 个参数

Get Toggl Desktop activity timeline showing application usage. PRIVACY NOTE: raw events include window titles that may contain sensitive document names, email subjects, chat text, URLs, OAuth pages, or database names; use include_events: false for privacy-conscious summary-only usage. Requires Toggl Track Desktop timeline sync to be enabled. Response semantics: summary is { [appName: string]: total_seconds }; total_events is the post-filter event count; returned_events is the returned events array length; truncated means only the events array was limited, never the summary. limit does not affect summary calculation. total_seconds is canonical; total_hours is rounded to 4 decimals for display.

该工具无需必填参数，直接调用即可

服务介绍

MCP Toggl

与您的时间跟踪对话。提取报告、启动计时器、检查桌面活动，并将原始的Toggl数据转化为有用的摘要，这些都可以通过Claude或任何兼容MCP的客户端完成。

npm
MCP
License
Toggl API

查看您一周的实际工作情况

您询问：“给我这一周的总结”

MCP服务器返回带有项目、工作区、客户、标签和运行中的计时器上下文的时间条目。您的客户端可以将这些信息转化为可读的总结：

在7个项目中记录了31个条目，总计32.7小时。周一是一个轻松的计划日，周二有一个长时间的实施块，周三专注于一个项目，而周五则变成了发货日。最大的项目占用了本周27%的时间，紧随其后的是两个较小的项目。

每周总结图表

服务器不会硬编码这段文字或图表。它以一种易于综合的形式暴露结构化的Toggl数据。

捕捉偏差

您询问：“我是否真的在那次PR审查条目中做了我所说的工作？”

toggl_get_timeline 可以比较跟踪条目的边界与Toggl Track Desktop活动：

该条目运行了1小时33分钟。大约67分钟是在审查工具上，5分钟分散在聊天应用上，其余时间为空闲或被修剪的时间线空间。这个条目大部分是正确的。

偏差检测图表

这在开具发票前、经过长时间上下文切换之后，或者当像“管理”这样的模糊条目开始隐藏过多的Slack和浏览器时间时非常有用。

随时间查看模式

您询问：“给我看一下上个月的概览”

每日和每周报告工具使客户端能够轻松渲染热图、发现连续趋势并显示强度变化：

月度热图

Toggl仍然是事实的来源。MCP层使得代理更容易检查、总结和可视化数据。

您可以询问的内容


What am I currently tracking?

How much time did I spend on the website project this month?

Start a timer for "PR review" on the Platform project

Show me yesterday's hours as a chart

What apps did I use most today?

Generate a daily report for last Friday

Compare this week to last week by project

Which day this month had the most billable work?

图表提示取决于您的MCP客户端。服务器返回结构化数据；如Claude之类的客户端决定如何渲染它。

为什么这很有用

丰富的响应：时间条目通过 project_name、client_name、workspace_name、tag_names 和标准化的运行计时器字段进行了丰富，因此客户端不需要进行第二次查询来进行常规报告。

智能缓存：工作区、项目、客户、任务和标签在首次读取后会被缓存。toggl_cache_stats 显示命中数、未命中数、加载的实体和命中率。

桌面活动时间线：toggl_get_timeline 从Toggl Track Desktop汇总应用程序使用情况，并在需要序列分析时返回原始事件。

隐私控制：时间线调用支持仅输出摘要（include_events: false）和标题编辑（redact_titles: true）。

周期快捷方式：today、yesterday、week、lastWeek、month 和 lastMonth 在有意义的工具中得到支持。

可恢复错误：工作区解析错误包括 available_workspaces，Toggl配额/速率限制错误包括结构化的重试提示。

快速开始

前提条件

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json 中：


{

  "mcpServers": {

    "mcp-toggl": {

      "command": "npx",

      "args": ["-y", "@verygoodplugins/mcp-toggl@latest"],

      "env": {

        "TOGGL_API_KEY": "your_api_key_here",

        "TOGGL_DEFAULT_WORKSPACE_ID": "123456"

      }

    }

  }

}

TOGGL_DEFAULT_WORKSPACE_ID 是可选的。如果您只有一个Toggl工作区，服务器可以自动解析它。如果您有多个工作区且没有设置默认值，那么工作区范围内的工具会返回可用的工作区ID，以便客户端可以使用 workspace_id 重试。

重启Claude Desktop，然后询问：


What am I currently tracking?

全局安装


npm install -g @verygoodplugins/mcp-toggl

mcp-toggl --help

工具

报告和洞察| 工具 | 功能描述 |

| --- | --- |
| toggl_daily_report | 按日期显示项目和工作区的工时。使用 format: "text" 显示文本或使用 "json" 输出结构化数据。 |
| toggl_weekly_report | 7天细分，包括每日总计和项目汇总。使用 week_offset: -1 获取上周的数据。 |
| toggl_get_time_entries | 按时间段、日期范围、工作区或项目获取原始条目。 |
| toggl_get_timeline | Toggl Track Desktop 应用程序使用情况摘要，可选包含原始事件。 |

计时器控制

工具 功能描述
toggl_get_current_entry 返回正在运行的计时器、已用秒数以及项目/工作区上下文。
toggl_start_timer 使用描述、可选项目/任务和标签启动计时器。
toggl_stop_timer 停止当前正在运行的计时器。

查询

工具 功能描述
toggl_check_auth 验证令牌访问权限并列出可用的工作区，而不暴露令牌。
toggl_list_workspaces 列出所有可访问的工作区。
toggl_list_projects 列出工作区中的项目，在首次获取后使用缓存读取。
toggl_list_clients 列出工作区中的客户，在首次获取后使用缓存读取。

缓存管理

工具 功能描述
toggl_warm_cache 在大量报告会话之前预取工作区、项目、客户和标签数据。
toggl_cache_stats 返回命中次数、未命中次数、命中率、加载的实体数量和缓存预热状态。
toggl_clear_cache 清除缓存数据。在创建或重命名 Toggl 实体后很有用。

汇总

工具 功能描述
toggl_project_summary 按时间段或日期范围计算每个项目的总工时。
toggl_workspace_summary 按时间段或日期范围计算每个工作区的总工时。

时间线隐私

Toggl Track Desktop 活动可能包括窗口标题。这些标题可能包含文档名称、电子邮件主题、聊天文本、URL、OAuth 页面或数据库名称。

仅汇总模式返回应用程序总计而没有原始事件：


{

  "period": "today",

  "include_events": false

}

带有编辑标题的事件保留顺序和持续时间，但移除标题：


{

  "period": "today",

  "redact_titles": true,

  "limit": 50

}

默认为完整事件模式：


{

  "period": "today"

}

不确定时，请使用 include_events: false。

配置参考

环境变量 是否必需 默认值 备注
TOGGL_API_KEY 是 - 用于您的 Toggl API 令牌的首选环境变量。
TOGGL_API_TOKEN 否 - 支持的别名，为了向后兼容。建议使用 TOGGL_API_KEY。
TOGGL_TOKEN 否 - 支持的别名，为了向后兼容。建议使用 TOGGL_API_KEY。
TOGGL_DEFAULT_WORKSPACE_ID 否 - 当工具需要工作区且未传递时使用。
TOGGL_CACHE_TTL 否 3600000 缓存生存时间（以毫秒为单位）。默认为1小时。
TOGGL_CACHE_SIZE 否 1000 最大缓存实体预算。
TOGGL_BATCH_SIZE 否 100 由 API 分页助手使用的批量大小。

注意事项

Toggl 速率限制和配额：在频繁请求期间，Toggl 可能会返回速率限制或配额错误。当 Toggl 提供时，服务器将返回结构化的重试信息。在大型报告会话之前预热缓存，以避免重复获取项目/客户/标签。

正在运行的计时器持续时间：Toggl 对于正在运行的条目使用负持续时间值。请从响应中读取 running 和 elapsed_seconds。

时间线可用性：toggl_get_timeline 需要启用 Toggl Track Desktop 时间线同步。如果未启用或尚未上传数据，该工具将返回 enabled: false 并提供设置指南。

时间线总计：limit 仅限制返回的原始事件。summary、total_seconds 和 total_hours 是根据所有匹配事件计算得出的。

本地开发


git clone https://github.com/verygoodplugins/mcp-toggl.git

cd mcp-toggl

npm install

npm run build

npm test

有用的命令：


npm run dev

npm run lint

npm run format

许可证

MIT。

由 Very Good Plugins 构建。

查看源码 项目主页

相关 MCP 服务

LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
可视化图表-MCP-Server
antvis/mcp-server-chart
这是一个基于AntV的模型上下文协议服务器，用于生成图表。它支持超过20种类型的图表，并且可以与多种桌面应用程序和平台一起使用。
微软Playwright
@microsoft/playwright-mcp
一种模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页交互，而无需使用视觉模型或截图。
MCP上下文模型文档
@upstash/context7-mcp
一种模型上下文协议服务器，它从库中直接获取最新、特定版本的文档和代码示例并将其引入LLM提示中，帮助开发人员在无需过时或虚构信息的情况下获得准确的答案。