Toggl跟踪MCP服务器

将您的Toggl Track时间跟踪数据连接到AI助手 --通过自然语言查询访问时间条目、项目、客户端和分析，默认情况下具有安全的只读访问和可选的写入功能。

🚨 免责声明：此项目由创建模糊实验室具有良好的氛围，并且没有得到Toggl Track的正式支持。请自行决定使用。

这有什么作用

通过向AI助手提出自然语言问题，改变您使用Toggl Track时间跟踪数据的方式，例如：

*“上周我在客户工作上花了多少时间？”*
*“这个月我工作效率最高的一天是哪一天？”*
*“显示所有标记为“会议”的时间条目”*
*“我花在哪个项目上的时间最多？”*
*“为营销项目生成时间摘要”*
*“显示过去一个月的团队时间条目”* （仅限管理员）
*“生成按用户分组的团队摘要”* （仅限管理员）
*“列出所有工作区用户及其ID”* （仅限管理员）
*“为“与客户会面”创建新的时间条目”* （仅写入模式）
*“为‘处理功能X’启动计时器”* （仅写入模式）
*“创建一个名为‘Acme Corp’的新客户，并注明‘第三季度SOW待定’”*
*为客户47847188创建一个新项目AIaaS-200-3001，可计费，从2026年5月1日开始，到2026年8月31日结束，预计120小时*
*“将Sam（用户11551609）和Tiffany（用户12299621）添加到项目213632529”*

🔒 缺省巩固安全 --通过环境变量以可选写入模式进行只读访问 🚀 即时设置 --可与任何兼容MCP的AI助手配合使用\ 📊 全覆盖 --访问时间条目、项目、客户、分析等\ 👥 团队报告 --管理员用户可以访问整个团队的时间跟踪数据

快速开始

1.获取您的Toggl Track API代币

登录您的Toggl Track帐户
首选 个人资料设置→ API代币
复制您的API令牌（确保其安全！）

2.安装和配置

macOS设置

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/fuzzylabs/toggl-track-mcp.git
cd toggl-track-mcp
uv sync

Linux/Windows安装程序

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
# OR for Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Clone and install
git clone https://github.com/fuzzylabs/toggl-track-mcp.git
cd toggl-track-mcp
uv sync

3.连接到您的AI助手

克劳德桌面版

将此添加到您的Claude Desktop配置文件中：

配置位置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "toggl-track": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/toggl-track-mcp",
        "python",
        "-m",
        "toggl_track_mcp"
      ],
      "env": {
        "TOGGL_API_TOKEN": "your_toggl_api_token_here",
        "TOGGL_WRITE_ENABLED": "false"
      }
    }
  }
}

光标

📋 快速设置：

复制此Cursor深度链接并将其粘贴到浏览器地址栏中：

cursor://anysphere.cursor-deeplink/mcp/install?name=toggl-track&config=eyJ0b2dnbC10cmFjayI6eyJjb21tYW5kIjoidXYiLCJhcmdzIjpbInJ1biIsIi0tZGlyZWN0b3J5IiwiL3BhdGgvdG8veW91ci90b2dnbC10cmFjay1tY3AiLCJweXRob24iLCItbSIsInRvZ2dsX3RyYWNrX21jcCJdLCJlbnYiOnsiVE9HR0xfQVBJX1RPS0VOIjoieW91cl90b2dnbF9hcGlfdG9rZW5faGVyZSJ9fX0K

💡 如何使用：

复制整个 cursor:// 上面的URL
将其粘贴到浏览器的地址栏中
按Enter键-这将打开Cursor并提示安装MCP服务器

注：点击按钮后，您需要：

更新路径 /path/to/your/toggl-track-mcp 到您的实际安装目录
替换 your_toggl_api_token_here 使用您的实际Toggl Track API代币

或者手动将其添加到光标MCP设置中：

{
  "toggl-track": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/your/toggl-track-mcp",
      "python",
      "-m",
      "toggl_track_mcp"
    ],
    "env": {
      "TOGGL_API_TOKEN": "your_toggl_api_token_here",
      "TOGGL_WRITE_ENABLED": "false"
    }
  }
}

其他MCP客户端

此服务器与任何MCP客户端兼容。有关MCP服务器配置，请参阅客户的文档。

💡 安装帮助：

使用紫外线（推荐）： 使用 uv run 命令如上所示-不需要Python路径！
Claude Desktop的紫外线路径： 使用完整路径 ~/.local/bin/uv （找到你的 which uv)
手动Python路径（如果不使用uv）：

- macOS（Homebrew）： /opt/homebrew/bin/python3 （苹果硅）或 /usr/local/bin/python3 （英特尔） - macOS（系统）： /usr/bin/python3 （如果可用） - 找到你的Python： 跑 which python3 在终端 - 窗户： 尝试 C:\Python311\python.exe

4.开始使用

重启你的AI助手
开始提问！

尝试以下示例查询：

*“显示我当前的时间条目”*\ *“我昨天记录了多少时间？”*\ *“我在做什么项目？”*\ *“生成每周时间报告”*\ *“显示本月的团队时间条目”* （仅限管理员）\ *“列出所有工作区用户”* （仅限管理员）

写入模式（可选）

默认情况下，MCP服务器在 只读模式 为了安全。要启用时间条目创建，请设置 TOGGL_WRITE_ENABLED 环境变量：

启用写入模式

更新您的MCP配置，以包括：

"env": {
  "TOGGL_API_TOKEN": "your_toggl_api_token_here",
  "TOGGL_WRITE_ENABLED": "true"
}

写入操作可用

启用写入模式后，您可以：

创建运行时间条目 -只需描述即可启动新计时器
创建已完成的时间条目 -添加具有特定持续时间的过去工作
分配给项目 -将时间条目链接到现有项目
设置计费状态 -将条目标记为可计费或不可计费
添加标签 -用逗号分隔的标签对条目进行分类
自定义开始时间 -回溯到特定时间的条目

写入模式查询示例

"Create a new time entry for 'Client meeting'"
"Start a timer for 'Working on feature X' and assign it to project 123"
"Add a 2-hour billable entry for 'Code review' from 2pm today"
"Create entry 'Documentation work' with tags 'writing, urgent'"

安全须知

环境封闭：除非明确启用，否则写入操作将完全禁用
无数据修改：仅支持创建新的时间条目，不支持编辑/删除
审计跟踪：所有创建的条目都包含用于跟踪的“toggl-track mcp”标识符
API费率限制：尊重Toggl的限速以防止滥用

您可以访问的内容

此MCP服务器提供 完全访问 到您的Toggl Track数据：

数据类型	你能做什么
👤 用户信息	查看个人资料、工作区、时区设置
⏱️ 电流定时器	检查运行时间输入、持续时间、描述
📊 时间条目	列表、搜索、按日期、项目、标签筛选
✏️ 创建条目	（仅写入模式）创建新的时间条目、启动/停止计时器
📂 项目	查看项目详细信息、状态、客户分配
🆕 创建项目	使用客户、颜色、计费、日期和估计小时数创建新项目
👥 客户	访问客户信息和关系
➕ 创建客户	使用可选注释创建新客户端
👤 项目成员	将用户添加到项目中（每次呼叫一个）；设置为经理
🏢 工作区	查看可用工作区和权限
🏷️ 标签	浏览所有标签进行分类
📈 分析	生成时间摘要、明细、报告
👥 团队报告	（仅限管理员）访问整个团队的时间条目、摘要和用户数据
🔍 工作区用户	（仅限管理员）列出所有具有ID的工作区成员以进行筛选

团队功能（需要管理员）

MCP服务器包括强大的团队报告功能，需要 工作区管理员权限:

团队时间条目

访问日期范围内的所有团队成员的时间条目
按特定用户、项目、客户或计费状态筛选
获取丰富的数据，包括用户名、电子邮件、项目详细信息和账单信息
支持大型数据集（每个请求最多1000个条目）

团队总结

生成按用户、项目或客户分组的汇总团队摘要
查看总时间、计费时间和生产率指标
格式化的持续时间显示，便于阅读
灵活的日期范围过滤

工作区用户管理

列出所有工作区成员及其ID和详细信息
对于按特定用户筛选团队报告至关重要
查看用户角色和活动状态

团队查询示例

使用管理员权限尝试以下操作：

*“显示上周的所有团队时间条目”*
*“生成按项目分组的本月团队摘要”*
*“昨天哪些团队成员的计费时间最多？”*
*“列出所有工作区用户，以便我可以筛选报告”*

⚠️ 重要：只有当您的Toggl Track帐户具有工作区管理员权限时，团队功能才能工作。普通用户在尝试访问团队数据时将收到相应的错误消息。

故障排除

常见问题

“没有名为'toggl_track_mcp'的模块”

使用紫外线： 确保您使用的是绝对目录路径 uv run --directory
手动设置： 验证Python可以找到已安装的包： pip list | grep fastmcp

“spawn uv ENOENT”或“找不到命令：uv”

先安装uv： curl -LsSf https://astral.sh/uv/install.sh | sh
安装后重新启动终端
验证安装： uv --version

“生成python ENOENT”（如果不使用uv）

切换到uv设置（推荐）或在配置中使用完整的Python路径
检查你的Python路径： which python3
尝试不同的常见路径： /usr/bin/python3, /usr/local/bin/python3, /opt/homebrew/bin/python3

“身份验证失败”

验证Toggl Track API令牌是否正确
检查您的Toggl帐户是否具有API访问权限（可能需要付费计划）

“需要管理员权限”或团队功能不起作用

团队功能需要Toggl Track中的工作区管理员权限
检查您的角色：配置文件设置→ 工作区→ 您的工作空间→ 检查您是否是管理员
如果需要，请联系您的工作区所有者以授予管理员访问权限

MCP工具未显示在您的AI助手中

配置更改后重新启动AI助手
检查配置文件语法是否为有效的JSON
验证文件路径是绝对的，而不是相对的

写入操作不起作用

检查 TOGGL_WRITE_ENABLED=true 在环境变量中设置
添加环境变量后重新启动AI助手
验证您是否有权在Toggl工作区中创建时间条目

“写入操作已禁用”错误

这 create_time_entry 工具需要 TOGGL_WRITE_ENABLED=true
这是一个安全功能，用于防止意外创建时间条目
更新MCP配置以包含环境变量

获取帮助

问题和Bug：
Toggl API文档： developers.track.toggl.com
MCP协议： 模型上下文协议.io

______________________________________________________________________

渲染部署（安全远程HTTP访问）

想要远程部署MCP服务器，以便多个用户可以通过HTTP访问它吗？部署到渲染，使用API密钥身份验证轻松进行云托管。

快速部署

![Deploy to Render](https://render.com/deploy?repo=https://github.com/fuzzylabs/toggl-track-mcp)

手动部署

复刻此仓库 转到您的GitHub帐户

创建渲染帐户 在 render.com

创建新的Web服务 并连接您的GitHub分支

配置服务：

- 构建命令： uv sync - 启动命令： uv run uvicorn toggl_track_mcp.server:app --host 0.0.0.0 --port $PORT - 计划： 免费（或选择付费计划以获得更好的性能）

设置环境变量 在渲染仪表板中：

- TOGGL_API_TOKEN：您的Toggl Track API代币 - MCP_API_KEY：用于身份验证的安全随机API密钥（请参阅下面的生成说明） - TOGGL_WRITE_ENABLED：设置为 "true" 启用时间条目创建（可选，默认为 "false")

部署 -Render将自动构建和部署您的服务

生成安全的API密钥

为生成安全随机API密钥 MCP_API_KEY 环境变量：

# Using Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Using OpenSSL  
openssl rand -base64 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

⚠️ 重要：安全存储此API密钥-您需要它来配置MCP客户端。

使用已部署的服务器

部署后，您将获得一个URL，如下所示 https://your-service.onrender.com。配置您的MCP客户端以使用：

克劳德桌面：

{
  "mcpServers": {
    "toggl-track": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "https://your-service.onrender.com/mcp/",
        "-H", "Content-Type: application/json",
        "-H", "Authorization: Bearer YOUR_MCP_API_KEY_HERE",
        "-d", "@-"
      ]
    }
  }
}

替换 YOUR_MCP_API_KEY_HERE 使用您在“渲染”中生成和设置的API键。

🔒 安全说明：只有当 MCP_API_KEY 设置环境变量。如果没有配置API密钥，服务器将接受未经验证的请求（对本地开发有用）。

直接HTTP访问：

# List available tools
curl -X POST https://your-service.onrender.com/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_MCP_API_KEY_HERE" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Get current time entry
curl -X POST https://your-service.onrender.com/mcp/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_MCP_API_KEY_HERE" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_current_time_entry",
      "arguments": {}
    },
    "id": 1
  }'

⚠️ 关于免费等级的说明： Render的免费层在不活动后会关闭服务。首次请求可能需要30-60秒才能唤醒服务。

______________________________________________________________________

对于开发者

开发设置

环境变量（用于开发）：

cp .env.example .env
# Edit .env and set:
# TOGGL_API_TOKEN=your_token_here
# TOGGL_WRITE_ENABLED=true  # Optional: enable write operations

运行测试：

uv run pytest

HTTP服务器（用于测试）：

uv run uvicorn toggl_track_mcp.server:app --reload
# Server available at http://localhost:8000/mcp/

API测试

测试架构终结点：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

测试获取当前时间条目：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_current_time_entry",
      "arguments": {}
    },
    "id": 1
  }'

测试团队时间条目（需要管理员）：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_team_time_entries",
      "arguments": {
        "start_date": "2025-06-01",
        "end_date": "2025-06-17"
      }
    },
    "id": 1
  }'

建筑

服务器： 带FastAPI后端的FastMCP框架
协议： 通过stdio实现模型上下文协议（MCP）
API Toggl跟踪API v9，具有可配置的读/写访问权限
身份验证： API令牌（基本身份验证）
安全： 环境门控写入操作

Toggl Track MCP

快速接入

详细介绍