Timetracker MCP

时间跟踪器mcp

MCP服务器+克劳德代码插件，用于跟踪每张工单的工作时间。准确记录使用AI代理所花费的实时时间——启动/停止/暂停/恢复跟踪、通过钩子进行空闲检测以及手动时间调整。

安装

作为Claude Code插件（推荐）

包括MCP服务器+活动挂钩，用于精确的空闲检测。

claude plugin install github:FrostBy/timetracker-mcp

手动MCP设置

没有钩子——仅基于时间跟踪器工具调用的空闲检测。

窗户：

{
  "timetracker": {
    "command": "cmd",
    "args": ["/c", "npx", "github:FrostBy/timetracker-mcp"],
    "env": {
      "IDLE_THRESHOLD_MINUTES": "60"
    }
  }
}

macOS/Linux：

{
  "timetracker": {
    "command": "npx",
    "args": ["github:FrostBy/timetracker-mcp"],
    "env": {
      "IDLE_THRESHOLD_MINUTES": "60"
    }
  }
}

工具

跟踪器_启动

开始跟踪工单的时间。自动暂停任何当前活动的工单。

• 如果票证已经处于活动状态，则返回当前条目（幂等）
• 如果票被暂停，则恢复
• 如果另一张票处于活动状态，则自动暂停（不停止）

跟踪器_停止

停止跟踪并获取时间摘要。

返回：总时间、暂停时间、调整、净工作时间。

跟踪器_暂停

暂停时间跟踪。

跟踪器_恢复

恢复暂停的时间跟踪。

跟踪器_调整

通过增减分钟数来调整跟踪时间。

跟踪器\_ get

获取票证的完整跟踪数据，包括原始JSON。

跟踪器状态

显示当前正在跟踪的内容。没有参数。

跟踪器ping

轻量级活动ping。更新 lastActivityAt 用于空闲检测。无输出。如果不使用插件挂钩，则很有用。

跟踪器列表

使用可选筛选器列出所有跟踪条目。

跟踪器报告

一段时间内按票汇总的时间报告。

怠速检测

服务器监视不活动状态，并在空闲时间超过阈值时自动暂停跟踪。

带有插件挂钩（推荐）

当作为插件安装时 PreToolUse 挂钩点火 每 工具调用（读取、编辑、Bash等）并将时间戳写入 .claude/activity-ping.jsonMCP服务器读取此文件进行空闲检测，涵盖所有代理活动，而不仅仅是时间跟踪器调用。

无挂钩

空闲检测仅基于直接的时间跟踪器工具调用(tracker_status, tracker_ping等等）。

配置

• 默认阈值：60分钟
• 可通过以下方式配置 IDLE_THRESHOLD_MINUTES env变量
• 可以通过以下方式覆盖每个条目 idleThresholdMinutes 在 tracker_start

自动恢复

当检测到空闲并且用户返回时，下一个工具调用会自动恢复跟踪——空闲时间被排除在外，不需要手动恢复。

时间计算

net = (stoppedAt - startedAt) - total_pauses + adjustments

• 减去暂停（手动和自动怠速）
• 调整可以增加或减少时间
• 净时间从不为负（下限为0）

门票转换

启动新票会自动暂停当前票（不停止）。随时切换回 tracker_start --它恢复暂停的票。

数据存储

跟踪数据存储在 {projectRoot}/.claude/timetrack.json.

• 项目根是通过MCP根或 PROJECT_DIR env变量
• 超过30天的已完成条目将自动清理

许可证

麻省理工学院