AI导哈

时间追踪与项目管理服务

Toggl MCP Server 是一个允许MCP客户端通过自然语言与Toggl Track交互的服务，支持时间追踪、项目管理和工作区操作。

  • by abhinav24jha
  • Python
  • 本地部署
  • 13 星标
  • 更新于
在 GitHub 查看 abhinav24jha/toggl-mcp-server

使用说明

Toggl MCP服务器

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

特性

工具

项目管理

  • 创建项目

    • 描述：在指定的Toggl工作区中创建新项目。
    • 输入:
      • 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响应。

  • 删除项目

    • 描述：删除指定工作区中由其名称标识的项目。
    • 输入:
      • project_name （str）：要删除的项目的确切名称。这是必填字段。
      • workspace_name （str，可选）：包含项目的工作区的名称。如果未提供，则默认为用户的默认工作区。
    • 输出：表示项目删除成功的确认消息（str）。

  • update_项目

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

  • get_all_项目

    • 描述：检索指定工作区内所有项目的列表。
    • 输入:
      • 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

    • 描述：获取当前运行时间条目的详细信息。
    • 输入：None（隐式使用用户的上下文）。
    • 输出：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跟踪帐户
  • 安装uv用于依赖关系管理

环境变量

创建一个 .env 文件内部 mcp_toggl_server 文件夹包含：

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代码+GitHub副本设置

  1. 在中配置MCP服务器 .vscode/mcp.json:
"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服务器可与任何兼容MCP的客户端配合使用。对于集成步骤：

  1. 对于Claude Desktop，请访问 MCP快速入门指南
  2. 对于其他MCP客户端，请参阅其各自的文档以了解服务器配置

注意：配置通常涉及指定服务器路径和环境变量，类似于上面的VS代码设置。

MCP检验员测试

要在开发中运行：

EMAIL=your_toggl_email PASSWORD=your_toggl_password mcp dev toggl_mcp_server.py

许可证

此MCP服务器根据MIT许可证获得许可。

相关 MCP