toggl-mcp

toggl-mcp

一个 Model Context Protocol (MCP) 服务，让 Claude 能够访问你的 Toggl Track 时间跟踪数据。

你可以向 Claude 提出以下问题：

• “我现在正在跟踪什么？”
• “这周我在每个项目上花了多少时间？”
• “在 Blog 项目中开始一个文档撰写计时器”
• “停止我的计时器”
• “我昨天做了什么？”

---

工具

工具	功能
get_current_timer	显示当前正在运行的时间记录
get_recent_entries	过去 N 天的时间记录（默认为 7 天）
get_projects	列出你的所有项目
get_summary	指定日期范围内按项目汇总的时间
start_timer	开始一条新的时间记录
stop_timer	停止当前计时器
get_profile	你的 Toggl 个人资料和工作区

---

设置

1. 获取 API 令牌

1. 前往 https://track.toggl.com/profile
2. 滚动到页面底部
3. 点击 API Token 下方的 “Click to reveal”
4. 复制令牌

2. 安装

npm install -g toggl-mcp

查找安装路径：

which toggl-mcp

3. 添加到 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "toggl": {
      "command": "/path/from/which/toggl-mcp",
      "env": {
        "TOGGL_API_TOKEN": "your_token_here"
      }
    }
  }
}

或者从源代码运行：

{
  "mcpServers": {
    "toggl": {
      "command": "node",
      "args": ["/path/to/toggl-mcp/dist/index.js"],
      "env": {
        "TOGGL_API_TOKEN": "your_token_here"
      }
    }
  }
}

重启 Claude Desktop。你应该会在 设置 → 开发者 中看到绿色的“运行中”徽章。

4. 测试

What am I currently tracking in Toggl?

---

示例查询

每日签到：

What have I tracked today in Toggl?

每周回顾：

Give me a summary of how I spent my time this week by project

开始跟踪：

Start a Toggl timer for "reviewing PRs" on my Engineering project

停止并汇总：

Stop my timer and tell me how long I worked

生产力分析：

How much time did I track last week vs the week before?
Which project took the most time?

---

开发

git clone https://github.com/yourusername/toggl-mcp
cd toggl-mcp
npm install
npm run build

# Test locally
TOGGL_API_TOKEN=your_token node dist/index.js

项目结构

toggl-mcp/
├── src/
│   ├── index.ts   # MCP server + tool definitions
│   └── toggl.ts   # Toggl API v9 client + formatters
├── package.json
├── tsconfig.json
└── README.md

---

速率限制

Toggl 的免费套餐允许每个工作区每小时发送 30 个请求。此 MCP 服务会尽可能批量处理调用（例如，并行获取项目和时间记录），确保正常使用时远低于限制。

---

贡献

欢迎提交 PR。扩展方向：

• 标签管理
• 客户列表
• 详细报告（按日细分）
• 时间记录编辑

---

许可证

MIT

---

致谢

使用 MCP TypeScript SDK 和 Toggl Track API v9 构建。