Toggl Track MCP Server

Toggl Track MCP 服务

用于集成 Toggl Track 时间跟踪功能的 Model Context Protocol（MCP）服务。此服务允许 Claude 和其他 MCP 客户端与您的 Toggl Track 账户交互，以管理项目和时间记录。

此服务由 Claude Code 100% 编写，只有 BUILD_APP.md 是我编写的，用于指导服务的创建 此服务尚未经过广泛测试（说实话，我几乎没看过代码！），因此肯定还有改进空间。

功能

• 获取项目：从您的 Toggl Track 账户获取所有项目
• 获取工作区：列出与您的账户关联的所有工作区
• 获取时间记录：提供详细的时间记录，并支持按日期范围和项目筛选
• 时间汇总：按项目汇总时间报告，并显示百分比
• 当前计时器：查看当前正在运行的计时器及已用时间
• 计时器控制：启动新计时器并停止当前运行的计时器
• 任务管理：创建并获取项目任务及其预计耗时
• 搜索记录：按描述文本查找时间记录
• 智能提示词：为常见时间跟踪查询提供预置对话开场白
• 安全的 API 令牌身份验证
• 输出格式清晰易读，便于大模型使用

快速开始

1. 获取 Toggl Track API 令牌

1. 前往您的 Toggl Track 个人资料设置
2. 从“API Token”部分复制您的 API 令牌
3. 配置时需要使用此令牌，请妥善保存

2. 构建 Docker 镜像

克隆此仓库并构建 Docker 镜像：

git clone [email protected]:vontell/toggl-track-mcp.git
cd toggl-track-mcp
docker build -t toggl-track-mcp .

3. 配置 Claude Desktop

将此服务添加到 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

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

5. 验证安装

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

• “我在 Toggl Track 中有哪些项目？”
• “为‘Code review’启动计时器”
• “我当前的计时器状态是什么？”

---

开发环境配置

用于开发和测试：

本地开发

创建虚拟环境：

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 Inspector 进行测试

mcp dev server.py

这会打开 MCP Inspector，以便进行交互式测试。

可用工具

get_projects

获取您 Toggl Track 账户中的所有项目及其详细信息，包括：

• 项目名称
• 工作区 ID
• 关联的客户
• 颜色标识
• 隐私设置

get_workspaces

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

• 工作区名称
• 工作区 ID

get_time_entries

获取详细的时间记录，并可选择筛选条件：

• start_date：按开始日期筛选（格式为 YYYY-MM-DD，默认为 7 天前）
• end_date：按结束日期筛选（格式为 YYYY-MM-DD，默认为今天）
• project_name：按指定项目名称筛选
• 按日期分组显示记录，包括描述、时长和每日总计

get_time_summary

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

• start_date：摘要的开始日期（默认为 7 天前）
• end_date：摘要的结束日期（默认为今天）
• project_name：聚焦于指定项目（可选）
• 显示各项目的总时长和百分比，以及总计

get_current_timer

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

• 显示活跃项目和描述
• 显示已用时间和开始时间
• 如果没有计时器正在运行，则返回“No timer running”

start_timer

启动新计时器：

• description：时间记录的描述（必填）
• project_name：要为计时器指定的项目名称（可选）
• 自动使用您的主工作区
• 返回确认信息和计时器详情

stop_current_timer

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

• 停止所有正在运行的计时器
• 显示最终时长和时间段
• 如果没有正在运行的计时器，则返回 "No timer running"

search_time_entries

按描述搜索时间条目：

• query：要在描述中搜索的文本（必填）
• start_date：搜索范围的开始日期（可选，默认为 30 天前）
• end_date：搜索范围的结束日期（可选，默认为今天）
• 执行不区分大小写的搜索，并计算总时长

get_project_tasks

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

• project_name：要获取任务的项目名称（必填）
• 显示任务名称、ID、状态（active/inactive）和预计时间
• 如果未找到项目，则返回有帮助的错误信息

create_project_task

为项目创建新任务：

• project_name：要在其中创建任务的项目名称（必填）
• task_name：新任务的名称（必填）
• estimated_hours：任务的预计小时数（可选）
• 返回包含任务 ID 和详情的确认信息

get_all_tasks

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

• 按项目和工作区整理显示任务
• 显示任务名称、ID、状态和预计时间
• 返回找到的任务总数
• 遇到无法访问任务的项目时会妥善跳过

示例提示词

此服务包含针对常见场景的预置提示词：

时间跟踪与分析

• detailed_time_report：获取时间条目的详细明细
• time_summary_report：按项目获取汇总的时间摘要
• productivity_analysis：分析工作模式和工作效率
• current_status_check：检查当前计时器和今天的活动
• project_deep_dive：深入分析特定项目的工作
• search_by_description：按描述文本搜索时间条目

计时器控制

• quick_start_timer：启动计时器，并填写描述和可选的项目
• stop_and_start_new：停止当前计时器并启动新的计时器
• timer_status_and_control：检查状态并获取计时器控制选项
• work_session_timer：启动专注工作时段，并设置休息提醒

任务管理

• view_project_tasks：查看特定项目的所有任务
• create_new_task：创建新任务，并设置可选的时间估算
• task_planning_session：规划和整理项目任务
• project_task_overview：查看所有项目任务的概览
• list_all_tasks：列出所有项目中的全部任务及详情

使用示例

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

项目与工作区查询

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

时间条目分析

• “显示我上周的时间条目”
• “我昨天做了什么？”
• “提供项目 X 的时间摘要”
• “这个月我在每个项目上花了多少时间？”
• “搜索我本周描述中包含 ‘meeting’ 的时间条目”

计时器控制

• “我当前的计时器状态是什么？”
• “在项目 ABC 上为 ‘Code review’ 启动计时器”
• “停止当前计时器”
• “为 ‘Planning session’ 启动计时器”

任务管理

• “显示项目 XYZ 的所有任务”
• “为项目 ABC 创建名为 ‘Database migration’ 的新任务”
• “创建一个预计需要 4 小时的任务”
• “帮我规划当前项目的任务”
• “列出我所有项目中的全部任务”

API 参考

此服务器使用 Toggl Track 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 次请求）。服务器会遵守这些限制，并在超出限制时提供相应的错误消息。

贡献

欢迎提交问题和功能改进请求！

许可证

此项目为开源项目，遵循标准条款。