关键词

时间追踪Toggl Track项目管理效率工具任务管理

使用说明

项目简介

Toggl MCP Server 是一个基于 Model Context Protocol (MCP) 构建的应用后端，它充当 LLM 客户端与 Toggl Track 服务之间的桥梁。通过此服务器，用户可以使用自然语言与 Toggl Track 进行交互，实现时间追踪、项目管理和工作区操作等功能。例如，用户可以通过 LLM 客户端（如VS Code + GitHub Copilot、Claude Desktop等）发送指令“创建一个名为‘文档编写’的项目”或“开始记录在‘项目A’上的工作时间”，服务器会将这些自然语言指令转换为 Toggl Track API 调用，并返回执行结果。

主要功能点

  • 项目管理:
    • 创建新项目 (create_project)
    • 删除项目 (delete_project)
    • 批量更新项目属性 (update_projects)
    • 获取所有项目列表 (get_all_projects)
  • 时间条目管理:
    • 创建新的时间条目，可用于开始计时器或记录已完成的工作时间 (new_time_entry)
    • 停止当前正在运行的计时器 (stop_time_entry)
    • 删除指定的时间条目 (delete_time_entry)
    • 获取当前正在运行的时间条目 (get_current_time_entry)
    • 更新时间条目的属性 (update_time_entry)
    • 获取指定日期范围内的时间条目 (get_time_entries_for_range)

安装步骤

  1. 环境准备:

    • 确保已安装 Python 3.11 或更高版本。
    • 拥有 Toggl Track 账户。
    • 安装 'uv' 包管理器（用于依赖管理，安装方法见仓库 README）。

  2. 配置环境变量:

    • 在 'mcp_toggl_server' 文件夹内创建 '.env' 文件，并填入您的 Toggl Track 邮箱和密码： 
      EMAIL=your_toggl_email
PASSWORD=your_toggl_password

  3. 安装依赖:

    • 克隆仓库到本地： 
      git clone [repository-url]
cd toggl-mcp-server
    • 创建虚拟环境并安装依赖： 
      uv venv
uv pip install --all

服务器配置

MCP 服务器需要配置在 MCP 客户端中才能使用。以下是针对不同 MCP 客户端的配置示例。您需要根据您的 MCP 客户端类型进行相应配置。

以 VS Code + GitHub Copilot 为例，在 '.vscode/mcp.json' 文件中进行如下配置：

"servers": {
  "toggl": {  // 服务器名称，可以自定义，如 "toggl"
    "type": "stdio", // 服务器类型，固定为 "stdio"
    "command": "uv", // 启动命令，这里使用 uv 运行 Python 脚本
    "args": [ // 启动参数
      "--directory", // 指定工作目录
      "/ABSOLUTE/PATH/TO/PARENT/FOLDER/toggl-mcp-server", // 替换为 toggl-mcp-server 仓库的绝对路径
      "run", // uv run 命令
      "toggl_mcp_server.py" // 运行 toggl_mcp_server.py 脚本
    ],
    "envFile": "${workspaceFolder}/toggl-mcp-server/.env" // 环境变量文件路径，指向 .env 文件
  }
}

配置参数说明:

  • 'servers': 配置多个 MCP 服务器。
  • 'toggl': 自定义服务器名称，用于在 MCP 客户端中标识该服务器。
  • 'type: "stdio"': 指定服务器使用标准输入输出流 (stdio) 进行通信。
  • 'command: "uv"': 指定用于启动服务器的命令，这里使用 'uv' 包管理器。如果 'uv' 不在 PATH 环境变量中，需要提供 'uv' 的完整路径。
  • 'args': 启动命令的参数列表。
    • '"–directory"': 指定工作目录为 'toggl-mcp-server' 仓库的父目录。请务必将 '/ABSOLUTE/PATH/TO/PARENT/FOLDER/toggl-mcp-server' 替换为您的本地仓库的绝对路径。
    • '"run"': 'uv run' 命令，用于运行 Python 脚本。
    • '"toggl_mcp_server.py"': 指定要运行的 Python 脚本为 'toggl_mcp_server.py'。
  • 'envFile': 指定环境变量文件路径，'${workspaceFolder}/toggl-mcp-server/.env' 表示 '.env' 文件位于 VS Code 工作区根目录下的 'toggl-mcp-server' 文件夹中。

其他 MCP 客户端配置:

对于 Claude Desktop 或其他 MCP 客户端，配置方法类似，通常需要指定服务器路径、启动命令和环境变量文件等信息。请参考相应 MCP 客户端的文档进行配置。

基本使用方法

  1. 启动 MCP 服务器:

    • 在 VS Code 中，鼠标悬停在 '.vscode/mcp.json' 文件中的服务器配置上，点击 "start" 按钮启动 Toggl MCP Server。
    • 或者，在终端中，进入 'toggl-mcp-server' 目录，运行命令 'uv run toggl_mcp_server.py' 启动服务器。

  2. 在 MCP 客户端中使用:

    • 启动服务器后，在 MCP 客户端（如 VS Code + GitHub Copilot 或 Claude Desktop）中，您可以使用自然语言指令调用 Toggl MCP Server 提供的工具。
    • 例如，在 VS Code + GitHub Copilot 中，切换到 Agent 模式，即可使用 '@toggl' 前缀调用 Toggl MCP Server 的工具，例如 '@toggl create_project name="新项目名称" workspace_name="我的工作区"'.

测试

您可以使用 MCP Inspector 工具进行开发测试。在终端中设置环境变量并运行以下命令：

EMAIL=your_toggl_email PASSWORD=your_toggl_password mcp dev toggl_mcp_server.py

信息

分类

生产力应用

访问项目