AI导哈

时间追踪集成服务

Toggl Track MCP Server是一个用于Toggl Track时间追踪集成的模型上下文协议服务器，允许Claude和其他MCP客户端管理项目和时间条目。

  • by vontell
  • Python
  • 本地部署
  • 15 星标
  • 更新于
在 GitHub 查看 vontell/toggl-track-mcp

使用说明

Toggl跟踪MCP服务器

用于Toggl-Track时间跟踪集成的模型上下文协议（MCP）服务器。此服务器允许Claude和其他MCP客户端与您的Toggl Track帐户交互，以管理项目和时间条目。

此服务器100%由Claude Code编写，除了BUILD_APP.md，我编写它是为了指导服务器的创建 这还没有经过广泛的测试（老实说，我几乎没读过代码！）所以肯定可以做出改进。

特性

  • 获取项目：从您的Toggl Track帐户检索所有项目
  • 获取工作区：列出与您的帐户关联的所有工作区
  • 获取时间条目：按日期范围和项目筛选的详细时间条目
  • 时间总结：按项目和百分比汇总的时间报告
  • 电流定时器：检查当前正在运行的内容和经过的时间
  • 计时器控制：启动新计时器并停止当前运行的计时器
  • 任务管理：创建和检索具有时间估计的项目任务
  • 搜索条目：按描述文本查找时间条目
  • 智能提示：用于常见时间跟踪查询的预构建对话启动器
  • 安全的API令牌身份验证
  • 格式化、可读的输出，供LLM使用

快速开始

1.获取您的Toggl Track API代币

  1. 去你的 Toggl跟踪配置文件设置
  2. 从“API令牌”部分复制您的API令牌
  3. 在配置步骤中，请将此令牌放在手边

2.构建Docker镜像

克隆此存储库并构建Docker镜像：

git clone git@github.com:vontell/toggl-track-mcp.git
cd toggl-track-mcp
docker build -t toggl-track-mcp .

3.配置克劳德桌面

将服务器添加到Claude Desktop配置文件中：

地点： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

{
  "mcpServers": {
    "Toggl Track": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOGGL_API_TOKEN",
        "toggl-track-mcp"
      ],
      "env": {
        "TOGGL_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

重要提示： 替换 "your_api_token_here" 使用您的实际Toggl Track API令牌。

4.重新启动克劳德桌面

更新配置后，重新启动Claude Desktop以加载新的MCP服务器。

5.验证安装

重新启动后，您应该可以向Claude提出以下问题：

  • “我在Toggl Track中有哪些项目？”
  • “启动“代码审查”计时器”
  • “我当前的计时器状态是什么？”

开发设置

对于开发和测试：

地方发展

创建虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate

安装依赖项：

pip install -r requirements.txt

设置API令牌：

export TOGGL_API_TOKEN="your_api_token_here"

MCP检验员测试

mcp dev server.py

这将打开MCP检查器进行交互式测试。

可用工具

get_projects

从您的Toggl Track帐户中检索所有项目，详细信息包括：

  • 项目名称
  • 工作区ID
  • 关联客户
  • 颜色编码
  • 隐私设置

get_workspaces

列出与您的Toggl Track帐户关联的所有工作区，包括：

  • 工作区名称
  • 工作区ID

get_time_entries

通过可选过滤获取详细的时间条目：

  • 开始日期：按开始日期筛选（YYYY-MM-DD格式，默认为7天前）
  • 结束日期：按结束日期筛选（YYYY-MM-DD格式，默认为今天）
  • 项目名称：按特定项目名称筛选
  • 显示按日期分组的条目，包括描述、持续时间和每日总计

get_time_summary

按项目获取汇总时间摘要：

  • 开始日期：摘要的开始日期（默认为7天前）
  • 结束日期：摘要的结束日期（默认为今天）
  • 项目名称：专注于特定项目（可选）
  • 按项目显示总小时数，包括百分比和总计

get_current_timer

检查当前正在运行的计时器：

  • 显示活动项目和描述
  • 显示经过的时间和开始时间
  • 如果没有活动，则返回“无计时器运行”

start_timer

启动新计时器：

  • 描述：时间输入说明（必填）
  • 项目名称：要分配计时器的项目名称（可选）
  • 自动使用您的主工作区
  • 返回带有计时器详细信息的确认

stop_current_timer

停止当前正在运行的计时器：

  • 停止任何活动计时器
  • 显示最终持续时间和时间段
  • 如果没有活动，则返回“无计时器运行”

search_time_entries

按描述搜索时间条目：

  • 怎么翻译：在描述中搜索的文本（必填）
  • 开始日期：搜索范围的开始日期（可选，默认为30天前）
  • 结束日期：搜索范围的结束日期（可选，默认为今天）
  • 不区分大小写的搜索，总时间计算

get_project_tasks

获取特定项目的所有任务：

  • 项目名称：要获取任务的项目名称（必填）
  • 显示任务名称、ID、状态（活动/非活动）和估计时间
  • 如果未找到项目，则返回有用错误

create_project_task

为项目创建新任务：

  • 项目名称：要在其中创建任务的项目名称（必填）
  • 任务名称：新任务的名称（必填）
  • 估计小时数：任务的估计小时数（可选）
  • 返回带有任务ID和详细信息的确认

get_all_tasks

获取所有项目中的所有任务：

  • 显示按项目和工作区组织的任务
  • 显示任务名称、ID、状态和估计时间
  • 返回找到的任务总数
  • 优雅地跳过没有任务访问权限的项目

示例提示

服务器包括常见场景的预构建提示：

时间跟踪与分析

  • 详细时间报告：获取时间条目的详细明细
  • 时间_摘要_报告：按项目获取汇总时间摘要
  • 生产率分析：分析工作模式和生产力
  • 当前状态检查：检查当前计时器和今天的活动
  • project_deep_dive：对具体项目工作的深入分析
  • 搜索_ _描述：按描述文本搜索时间条目

计时器控制

  • 快速启动计时器：使用描述和可选项目启动计时器
  • stop_and_start_new：停止当前计时器并启动新计时器
  • 时间_状态_和控制：检查状态并获取定时器控制选项
  • work_session_timer：通过休息提醒开始专注的工作会议

任务管理

  • view_project_tasks：查看特定项目的所有任务
  • 创建新任务：创建具有可选时间估计的新任务
  • 任务规划会话：计划和组织项目的任务
  • 项目任务概述：获取所有项目的任务概览
  • list_all_任务：列出所有项目中的所有任务及其详细信息

示例用法

在Claude Desktop中安装后，您可以询问：

项目和工作空间查询

  • “我在Toggl Track中有哪些项目？”
  • “显示我的Toggl工作区”
  • “列出我所有的时间跟踪项目”

时间输入分析

  • “显示我上周的时间条目”
  • “我昨天做了什么？”
  • “给我一份项目X的时间总结”
  • “这个月我在每个项目上花了多少时间？”
  • “在我的时间条目中搜索本周的‘会议’”

计时器控制

  • “我当前的计时器状态是什么？”
  • “启动ABC项目的‘代码审查’计时器”
  • “停止我当前的计时器”
  • “为“计划会话”启动计时器”

任务管理

  • “显示项目XYZ的所有任务”
  • 为ABC项目创建一个名为“数据库迁移”的新任务
  • “创建一个估计时间为4小时的任务”
  • “帮助我规划当前项目的任务”
  • “列出我所有项目中的所有任务”

api参考

此服务器使用 Toggl跟踪API v9.使用的关键端点：

  • GET /api/v9/me/projects -获取用户项目
  • GET /api/v9/workspaces -获取用户工作区
  • GET /api/v9/me/time_entries -获取时间条目
  • GET /api/v9/me/time_entries/current -获取当前运行计时器
  • POST /api/v9/workspaces/{id}/time_entries -启动新计时器
  • PATCH /api/v9/workspaces/{id}/time_entries/{id}/stop -停止计时器
  • GET /api/v9/workspaces/{id}/projects/{id}/tasks -获取项目任务
  • POST /api/v9/workspaces/{id}/projects/{id}/tasks -创建新任务

发展

项目结构

toggl-track-mcp/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variable template
└── README.md             # This file

添加新功能

要使用附加的Toggl Track功能扩展此服务器，请执行以下操作：

  1. 向中添加新方法 TogglClient 类
  2. 创建新的 @mcp.tool() 装饰功能
  3. 处理身份验证和错误情况
  4. 用新功能更新此README

认证

此服务器使用Toggl Track的API令牌身份验证方法。令牌应通过以下方式提供 TOGGL_API_TOKEN 环境变量。

安全说明：永远不要将API令牌提交到版本控制。始终使用环境变量或安全配置管理。

错误处理

该服务器包括全面的错误处理功能，用于：

  • 缺少API令牌配置
  • 网络连接问题
  • API身份验证失败
  • API响应格式不正确

速率限制

Toggl Track API具有速率限制（大约每秒1个请求）。服务器遵守这些限制，并在超过限制时提供适当的错误消息。

贡献

请随时提交问题和增强请求！

许可证

这个项目是开源的，可以在标准条款下使用。

相关 MCP