Toggl MCP Server

Toggl MCP Server

允许 MCP 客户端与 Toggl Track 交互，通过自然语言进行时间追踪、项目管理和工作区操作。

功能

工具

项目管理

• create_project

  • 描述：在指定的 Toggl 工作区中创建一个新项目。
  • 输入：
    • name (str)：要创建的项目名称。此字段为必填项。
    • workspace_name (str, optional)：要创建项目的工作区名称。如果未提供，则默认为用户的默认工作区。
    • active (bool, optional)：指定项目是否处于启用状态。默认为 True。
    • billable (bool, optional)：指定项目是否可计费。默认为 False。
    • client_id (int, optional)：与项目关联的客户 ID。
    • color (str, optional)：分配给项目的十六进制颜色代码（例如，"#FF0000"）。
    • is_private (bool, optional)：指定项目是否为私有项目。默认为 True。
    • start_date (str, optional)：项目的开始日期，采用 ISO 8601 格式（例如，"YYYY-MM-DD"）。
    • end_date (str, optional)：项目的结束日期，采用 ISO 8601 格式（例如，"YYYY-MM-DD"）。
    • estimated_hours (int, optional)：项目的预估小时数。
    • template (bool, optional)：指定项目是否为模板。默认为 False。
    • template_id (int, optional)：用于创建项目的模板 ID。
  • 输出：包含新创建项目数据的 JSON 响应。

• delete_project

  • 描述：删除指定工作区中按名称标识的项目。
  • 输入：
    • project_name (str)：要删除的项目的确切名称。此字段为必填项。
    • workspace_name (str, optional)：包含该项目的工作区名称。如果未提供，则默认为用户的默认工作区。
  • 输出：确认项目已成功删除的消息 (str)。

• update_projects

  • 描述：使用补丁操作批量更新指定工作区中的多个项目。
  • 输入：
    • project_names (List[str])：包含要更新的项目名称的列表。此字段为必填项。
    • operations (List[dict])：要应用于所选项目的补丁操作列表。每项操作都是一个字典，用于指定操作类型 (op)、字段路径 (path) 和新值 (value)（例如，{"op": "replace", "path": "/active", "value": false}）。此字段为必填项。
    • workspace_name (str, optional)：包含这些项目的工作区名称。如果未提供，则默认为用户的默认工作区。
  • 输出：包含已更新项目数据的 JSON 响应。

• get_all_projects

  • 描述：获取指定工作区中的所有项目列表。
  • 输入：
    • workspace_name (str, optional)：要从中获取项目的工作区名称。如果未提供，则默认为用户的默认工作区。
  • 输出：包含在指定工作区中找到的项目数据对象列表的 JSON 响应。

时间条目管理

• new_time_entry

  • 描述：创建新的时间条目。可用于启动计时器（仅提供 start，或既未提供 start 也未提供 duration 时），也可用于记录已完成的时间条目（提供 start 和 stop，或提供 start 和 duration 时）。
  • 输入：
    • description (str)：时间条目的描述。
    • workspace_name (str, optional)：工作区名称。默认为用户的默认工作区。
    • project_name (str, optional)：要与此时间条目关联的项目名称。
    • tags (List[str], optional)：要应用于此时间条目的一组标签名称。
    • start (str, optional)：条目的开始时间，采用 ISO 8601 格式（例如 "2023-10-26T10:00:00Z"）。创建正在计时的条目时，默认为当前时间。
    • stop (str, optional)：条目的停止时间，采用 ISO 8601 格式。若提供，则会创建已完成的条目。
    • duration (int, optional)：条目的持续时间，单位为秒。若提供了 start 但未提供 stop，则由 duration 确定停止时间。若未提供 start，负的持续时间会启动正在运行的计时器。
    • billable (bool, optional)：是否将此时间条目标记为可计费。默认为 False。
    • created_with (str, optional)：创建此条目的应用名称。默认为 "MCP"。
  • 输出：包含所创建时间条目数据的 JSON 响应。

• stop_time_entry

  • 描述：停止当前正在运行的时间条目。
  • 输入：
    • workspace_name (str, optional)：条目所在工作区的名称。默认为用户的默认工作区。
  • 输出：包含已停止时间条目数据的 JSON 响应。

• delete_time_entry

  • 描述：根据描述和开始时间删除指定的时间条目。
  • 输入：
    • time_entry_description (str)：要删除的时间条目的准确描述。
    • start_time (str)：用于识别条目的准确开始时间，采用 ISO 8601 格式。
    • workspace_name (str, optional)：条目所在工作区的名称。默认为用户的默认工作区。
  • 输出：成功删除后返回成功确认消息 (str)。

• get_current_time_entry

  • 描述：获取当前正在运行的时间条目的详细信息。
  • 输入：无（隐式使用用户的上下文）。
  • 输出：包含当前正在运行的时间条目数据的 JSON 响应；若当前没有正在运行的时间条目，则返回 None。

• update_time_entry

  • 描述：更新现有时间条目的属性，该条目通过描述和开始时间识别。
  • 输入：
    • time_entry_description (str)：要更新的时间条目的当前描述。
    • start_time (str)：用于识别条目的准确开始时间，采用 ISO 8601 格式。
    • workspace_name (str, optional)：条目所在工作区的名称。默认为用户的默认工作区。
    • new_description (str, optional)：时间条目的新描述。
    • project_name (str, optional)：要与条目关联的新项目名称。设为空字符串 "" 可移除项目关联。
    • tags (List[str], optional)：新的标签名称列表。此列表将替换所有现有标签。提供空列表 [] 可移除所有标签。
    • new_start (str, optional)：采用 ISO 8601 格式的新开始时间。
    • new_stop (str, optional)：采用 ISO 8601 格式的新停止时间。
    • billable (bool, optional)：新的可计费状态。
  • 输出：包含已更新时间条目数据的 JSON 响应。

• get_time_entries_for_range

  • Description：检索指定日期范围内的时间条目，该范围根据相对于当天的偏移量定义。
  • Input：
    • from_day_offset (int)：相对于今天的起始日期偏移量（例如，0 表示今天，-1 表示昨天，-7 表示一周前）。
    • to_day_offset (int)：相对于今天的结束日期偏移量（例如，0 表示今天，1 表示明天）。范围包含起始日期和结束日期。
    • workspace_name (str, optional)：要从中获取条目的工作区名称。默认为用户的默认工作区。
  • Output：JSON 响应，其中包含指定日期范围内的时间条目列表。

开始使用

先决条件

• Python 3.11+
• Toggl Track 账户
• 已安装 uv，用于管理依赖项

环境变量

在 mcp_toggl_server 文件夹中创建 .env 文件，内容如下：

EMAIL=your_toggl_email
PASSWORD=your_toggl_password

如果使用 Toggl API 令牌：

EMAIL=xxxx
PASSWORD="api_token"

其中 xxxx 表示你的个人令牌

安装

首先安装 uv： - 对于 MacOS/Linux： bash curl -LsSf https://astral.sh/uv/install.sh | sh - 对于 Windows： bash powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

之后请重启终端，以确保可以识别 uv 命令。

现在，让我们克隆代码库并设置项目：

git clone [repository-url]
cd mcp_toggl_server
uv venv
uv pip install --all

与开发工具集成

VS Code + GitHub Copilot 设置

1. 在 .vscode/mcp.json 中配置 MCP 服务：

"servers": {
  "toggl": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "--directory",
      "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp_toggl_server",
      "run",
      "toggl_mcp_server.py"],
    "envFile": "${workspaceFolder}/mcp_toggl_server/.env"
  }
}

2. 更新配置：

   • 将 /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp_toggl_server 替换为服务的绝对路径
   • 你可能需要在 command 字段中填写 uv 可执行文件的完整路径。在 MacOS/Linux 上运行 which uv，或在 Windows 上运行 where uv，即可获取该路径

3. 启用服务：

   • 将鼠标悬停在服务配置 /.vscode/mcp.json 上，查找启动按钮
   • 点击启动，让 Copilot 发现可用工具
   • 在 Copilot 中切换到 Agent 模式

如需详细的设置说明，请参阅：

• VS Code 中的 MCP 服务
• Copilot Agent 模式

与其他 MCP 客户端集成

Toggl MCP Server 可与任何兼容 MCP 的客户端配合使用。集成步骤如下：

1. 对于 Claude Desktop，请访问 MCP 快速入门指南
2. 对于其他 MCP 客户端，请参阅相应文档，了解服务配置方式

注意：配置通常需要指定服务路径和环境变量，方式与上述 VS Code 设置类似。

使用 MCP Inspector 进行测试

在开发环境中运行：

EMAIL=your_toggl_email PASSWORD=your_toggl_password mcp dev toggl_mcp_server.py

许可证

此 MCP 服务采用 MIT 许可证。