STARWARCLOUD STARWAR.AI
返回市场
时间追踪-MCP服务器

时间追踪-MCP服务器

作者：abhinav24jha12 星标更新：2025-09-16
安装使用来源：spider==github.com

项目介绍

Toggl MCP Server

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

功能

工具

项目管理

  • create_project

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

  • delete_project

    • 描述：删除指定工作区内通过名称标识的项目。
    • 输入：
      • project_name (str): 要删除的项目的精确名称。这是必填字段。
      • workspace_name (str, 可选): 包含项目的工区名称。如果没有提供，默认为用户的默认工区。
    • 输出：成功删除项目的确认消息（str）。

  • update_projects

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

  • get_all_projects

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

时间条目管理

  • new_time_entry

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

  • stop_time_entry

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

  • delete_time_entry

    • 描述：根据描述和开始时间删除特定的时间条目。
    • 输入：
      • time_entry_description (str): 要删除的时间条目的精确描述。
      • start_time (str): 用于识别的条目的精确开始时间，ISO 8601 格式。
      • workspace_name (str, 可选): 包含条目的工区名称。默认为用户的默认工区。
    • 输出：成功删除后的确认消息（str）。

  • get_current_time_entry

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

  • update_time_entry

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

  • get_time_entries_for_range

    • 描述：检索在指定日期范围内的条目，该范围由从今天起的偏移量定义。
    • 输入：
      • from_day_offset (int): 开始日期的偏移量，从今天起（例如，0 表示今天，-1 表示昨天，-7 表示一周前）。
      • to_day_offset (int): 结束日期的偏移量，从今天起（例如，0 表示今天，1 表示明天）。该范围包括开始和结束日期。
      • workspace_name (str, 可选): 要从中获取条目的工区名称。默认为用户的默认工区。
    • 输出：包含在指定日期范围内找到的时间条目列表的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 Server：
"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"
  }
}

  1. 更新配置：

    • 将 /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp_toggl_server 替换为服务器的绝对路径
    • 你可能需要在命令字段中放置 uv 可执行文件的完整路径。你可以通过在 MacOS/Linux 上运行 which uv 或在 Windows 上运行 where uv 来获取此路径。

  2. 启用服务器：

    • 当悬停在服务器配置 /.vscode/mcp.json 上时，查找启动按钮
    • 单击启动以让 Copilot 发现可用工具
    • 切换到 Copilot 的代理模式

有关详细设置说明，请参阅：

其他 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 许可证。