Toggl Track MCP 服务器

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

本服务器完全由 Claude Code 编写，除了我编写的 BUILD_APP.md 文件，该文件用于指导服务器的创建。 本服务器尚未经过广泛测试（老实说，我几乎没读过代码！），因此肯定可以进行改进。

功能

• 获取项目：从您的 Toggl Track 账户中检索所有项目
• 获取工作区：列出与您的账户关联的所有工作区
• 获取时间条目：按日期范围和项目过滤的详细时间条目
• 时间汇总：按项目聚合的时间报告，并带有百分比
• 当前计时器：检查当前运行的内容及已用时间
• 计时器控制：启动新的计时器并停止当前运行的计时器
• 任务管理：创建和检索带有时间估算的项目任务
• 搜索条目：通过描述文本查找时间条目
• 智能提示：预构建的对话启动器，用于常见的时间跟踪查询
• 安全的 API 令牌认证
• 格式化、可读的输出供 LLM 消费

快速开始

1. 获取您的 Toggl Track API 令牌

1. 前往您的 Toggl Track 个人资料设置
2. 从“API 令牌”部分复制您的 API 令牌
3. 在配置步骤中保留这个令牌

2. 构建 Docker 镜像

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

git clone git@github.com:vontell/toggl-track-mcp.git
cd toggl-track-m
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 中有哪些项目？”
• “启动一个‘代码审查’计时器”
• “我的当前计时器状态是什么？”

---

开发环境设置

为了开发和测试：

本地开发

创建虚拟环境：

python -m venv .venv
source .venv/bin/activate  # 在 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

检查当前运行的计时器：

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

start_timer

启动一个新的计时器：

• description：时间条目的描述（必需）
• project_name：分配计时器的项目名称（可选）
• 自动使用您的主要工作区
• 返回确认信息和计时器详情

stop_current_timer

停止当前运行的计时器：

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

search_time_entries

通过描述搜索时间条目：

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

get_project_tasks

获取特定项目的全部任务：

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

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 的时间摘要”
• “这个月我在每个项目上花了多少时间？”
• “搜索本周内带有‘会议’的时间条目”

计时器控制

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

任务管理

• “显示项目 XYZ 的全部任务”
• “为项目 ABC 创建一个名为‘数据库迁移’的新任务”
• “创建一个带有 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              # 主 MCP 服务器实现
├── requirements.txt       # Python 依赖项
├── .env.example          # 环境变量模板
└── README.md             # 本文件

添加新功能

要扩展此服务器以增加额外的 Toggl Track 功能：

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

认证

此服务器使用 Toggl Track 的 API 令牌认证方法。令牌应通过 TOGGL_API_TOKEN 环境变量提供。

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

错误处理

服务器包括全面的错误处理，涵盖：

• 缺失 API 令牌配置
• 网络连接问题
• API 认证失败
• 错误的 API 响应

速率限制

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

贡献

欢迎提交问题和增强请求！

许可

此项目是开源的，并根据标准条款提供。