pomodoro-timer

通过 Claude 追踪工时，无需安装，免费使用服务器

入选 Awesome MCP Servers - 目录条目 | 在线托管端点，免费套餐，无需注册。

无需离开 AI 聊天即可追踪可计费工时。只需说“为 acme 改版项目启动计时器”，继续工作，然后询问“我本周按项目统计的工时”或“8 月 acme 项目的发票明细”。它会持续计时，让你补记忘记追踪的工时，按项目应用时薪，并将结果整理成报告、CSV 文件或发票明细。所有数据都以纯 JSON 格式存储在你自己的设备上。

由 theluckystrike 构建。

已收录于 官方 MCP Registry（io.github.theluckystrike/time-tracker-timesheet-billable-hours）。

已收录于 AI Product Index - 在线远程端点：mcp.zovo.one/s/time-tracker，免费套餐，无需注册。

通过聊天追踪可计费工时，并直接生成报告或发票明细，零配置，所有数据都保存在本地。

60 秒安装

@theluckystrike/mcp-time-tracker 的 npm 发布尚在等待中。在此期间，可使用 .mcpb 一键安装包，或克隆并构建；以下两种方式均已验证。

一键安装（.mcpb）：从最新版本下载 time-tracker.mcpb，然后在 Claude Desktop 中双击： https://github.com/theluckystrike/mcp-servers/releases/latest

（claude_desktop_config.json）：

{
  "mcpServers": {
    "time-tracker": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-time-tracker"]
    }
  }
}

Claude Code：

claude mcp add time-tracker -- npx -y @theluckystrike/mcp-time-tracker

（.cursor/mcp.json）：

{
  "mcpServers": {
    "time-tracker": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-time-tracker"]
    }
  }
}

上述 npx 方式将在软件包发布后立即可用。在此之前，请使用上方的 .mcpb 安装包，或使用以下准确的三条命令从源代码构建：

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/time-tracker

然后将客户端的 command 指向 node，并传入一个参数：servers/time-tracker/dist/index.js 的绝对路径。

要使用 Pro 模式，请在同一配置块中设置 MCP_LICENSE_KEY，或使用你的密钥调用一次 license_activate。

工具

工具	功能
timer_start	为项目启动计时器（可选任务、标签、费率和货币）。启动新的计时器会停止并记录旧计时器。若输入的项目名称部分匹配且只匹配一个现有项目，则使用该项目。
timer_stop	停止正在运行的计时器，写入记录并返回时长。
timer_status	查看当前正在计时的内容、已计时多久以及今天的总时长。
entry_add	记录已完成的工作时间（开始和结束时间或分钟数），费率和货币为可选项：费率为“每小时 90 欧元”时，2.5 小时将计费 EUR 225.00。部分项目名称的解析方式与 timer_start 相同。
entry_list	按日期范围和项目筛选的精简记录表。
entry_edit	更改记录的任意字段。
entry_delete	按 ID 删除记录。
project_set_rate	设置用于金额合计的时薪和货币（货币可填写代码或名称：EUR、euros、pounds、zl）。apply_to_existing: true 会按新费率重新计算该项目已记录的时间；添加 only_missing: true 只会修改未设置费率的记录。
report	查看某个时段的工时和金额，可按项目、日期、任务或标签分组；省略 group_by 时，显示按货币统计的总额。支持表格、JSON 或 CSV。已开票的工时不会计入；传入 unbilled_only: false 可查看完整工时表。
export_csv	将记录写入 CSV 文件并返回路径。
invoice_summary	为单个项目生成可用于开票的明细项：工时、费率、金额、总额，使用记录工时时所用的货币。每个任务和费率各占一行，因此不会出现无人认可的混合费率。返回明细对应的 entry_ids，并跳过已开票工时（unbilled_only: false 会包含这些工时）。免费版支持最近 7 天，Pro 版支持完整历史记录中的任意时段。
entry_mark_billed	用发票编号标记已开票的工时（使用 invoice_summary 返回的 ids，或指定 project + from + to），这样 report 和 invoice_summary 就不会再提供这些工时，也能避免重复开票。
license_status	查看许可证是 Free 还是 Pro，以及升级方式。
license_activate	激活 Pro 密钥（离线验证）。

此外还提供资源 timetracker://today（今日摘要）和提示词 daily_standup （根据昨天和今天记录的时间撰写站会更新）。

你可以这样说

无需提供工具名称。以下句子已在服务器上实际测试；对应的工具列出了响应工具。

你说	工具
“为 Acme 网站项目启动计时器。”	timer_start
“停止计时器并告诉我工作了多久。”	timer_stop
“现在正在计时什么？已经计时多久了？”	timer_status
“记录我昨天为 Acme 做设计评审的 2.5 小时工作，时薪 90 欧元。”	entry_add
“显示我本周 Acme 的记录。”	entry_list
“把上一条记录的设计评审改成 API 重构。”	entry_edit
“删除我刚才重复记录的那条记录。”	entry_delete
“将 Acme 的时薪设为每小时 90 EUR。”	project_set_rate
“我这个月开票了多少小时？按项目分组。”	report
“给我 Acme 8 月的发票明细。”	invoice_summary
“我已将这些工时计入发票 INV-2026-0001。”	entry_mark_billed

另外还有两个值得了解的功能：“将我的工时导出为 CSV，发给我的簿记员”（export_csv）和“根据昨天和今天的工作撰写我的站会更新”（daily_standup 提示词）。

实例演示

这是审计记录 docs/USER_VALUE_R2.md 中的一段真实对话，数字保持不变。

You: Log 2.5 hours yesterday for Acme, design review, at 90 euros an hour.

  entry_add { project: "Acme", ... }
  -> "Acme" resolved to the existing project "Acme website"
  -> rate "90 euros an hour" parsed as EUR 90.00/h

Assistant: Logged 2.50 h for Acme website - design review at EUR 90.00/h = EUR 225.00.

You: How much do I bill Acme this week? Give me invoice lines.

  invoice_summary { project: "Acme website", from: "2026-08-31", to: "2026-09-02" }

Assistant: Invoice summary - Acme website
  design review    2.50 h   EUR 90.00/h   EUR 225.00
  TOTAL            2.50 h                 EUR 225.00

每项操作各调用一次。费率及其货币会始终一并传递：报告不会只显示一个没有货币单位的“225”，也不会意外变成“$225”。

第二个实例演示：周报和 daily_standup 提示词。

You: How many hours did I put into Acme this week, grouped by task?

  report { project: "Acme website", from: "2026-08-27", to: "2026-09-02", group_by: "task" }

Assistant: Acme website, 2026-08-27 to 2026-09-02
  design review   2.50 h   EUR 225.00
  TOTAL           2.50 h   EUR 225.00

You: Write my standup update.

  (prompt) daily_standup

Assistant: Yesterday: 2.50 h on Acme website (design review).
Today: nothing logged yet.

已开票时数结算

已开具发票的时数就算结清了。entry_mark_billed {ids, invoice_number} 会为这些条目写入 billed_at 和 billed_invoice；此后，report 和 invoice_summary 默认会跳过这些条目，因此下个月“向 Acme 开票”时，不会再次为已付款的工作开票。整份工时表仍然保留：对其中任意工具传入 unbilled_only: false 即可查看全部内容。invoice_summary 会返回其使用的 entry_ids，方便在发票开具后直接传给 entry_mark_billed。

report 和 invoice_summary 有意回答相互重叠的问题：report 用于查看“用了多少时间、产生多少费用”，并可按任意方式分组；invoice_summary 用于“提供可放入发票的明细行”，这是针对同一项目条目的更精简、适合发票格式的视图。

数据存储方式

条目、项目和费率都存储在一个 JSON 文件中： ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/time-tracker/data.json。

每次写入（启动或停止计时器、添加、编辑或删除条目、设置费率）都会在一个建议锁文件保护下进行，锁文件位于 .../time-tracker/.lock。锁会在整个加载、修改和保存过程中保持，因此两个重叠调用不会交错执行并损坏文件。保存时会先写入临时文件，再将其重命名到目标位置，因此即使发生崩溃或进程在写入过程中被终止，留下的也只会是旧文件或新文件，不会是写了一半的文件。读取操作（entry_list、report、timer_status、export_csv）不会加锁。

如需备份数据，只需复制 data.json 文件（如果存在 .lock，也可以一并复制，不过其中不含数据）。这里没有数据库，也没有隐藏的第二个文件。

如果 data.json 无法读取或不是有效的 JSON，服务不会将其视为“尚无数据”。它会逐字节原样移走该文件，并将其命名为 data.json.corrupt-<timestamp>，写入 data.json.corrupt 标记文件，并让所有工具（包括读取工具）都返回 data file is corrupt; moved to ...; nothing was written。恢复有效的 data.json（隔离副本就在原处），并删除标记文件，即可继续使用。在此期间，任何内容都不会被覆盖。

日期、时间和费率

• 未指定时区偏移量的时间戳均为你的本地时间。 2026-09-02T09:00:00 表示你所在位置的 09:00，而不是 UTC。传入明确的偏移量（2026-09-02T09:00:00+02:00）或末尾带 Z，系统就会严格按该时间处理。
• 仅包含日期的边界涵盖完整的本地日期。 from: "2026-09-01" 表示当地 1 日的 00:00:00， to: "2026-09-30" 表示当地 30 日的 23:59:59.999，因此按日期报告的整个月会包含最后一天。 带有时间的时间戳则按给定值使用。
• 条目会按时间窗口截取。 在 from 之前开始或在 to 之后结束的条目，只按其落在时间段内的部分 计算，不会计算全部时长，也不会完全忽略。
• 按天分组时，条目会在当地午夜拆分。 从 23:30 到 01:30 的工作时长，在第一天计为 0.5 小时， 在第二天计为 1.5 小时，跨月时也一样。timer_status 只统计条目或运行中计时器在今天午夜之后的部分。
• 费率字符串会被解析，不会被猜测。 "1,200 USD" 表示 1200（逗号后恰好有三位数字时，逗号视为 千位分隔符）；"12,50 EUR" 表示 12.50（明确的欧洲小数格式）；"1.200,50" 表示 1200.50。 对于可能有两种含义的格式（如 "1,2345"），系统会拒绝解析并提供计算示例，而不会将其误读为错误的数字。
• 费率会在记录时间时保存。 entry_add 和 timer_stop 会将生效的时薪和货币保存到条目中，报告和 发票会使用该保存的费率。因此，project_set_rate 仅适用于未来的条目；传入 apply_to_existing: true 可重新设置该项目已记录时间的费率。此操作会重新标记该项目的每个条目，包括已有费率的条目，并在响应 中说明变更数量和项目的新总额。添加 only_missing: true 后，只会修改未自行保存费率的条目。
• 标签行会有重叠。 在 group_by: "tag" 中，标记了 dev 和 meeting 的条目会同时出现在两行中； 总时长只会根据各条目计算一次，因此绝不会等于各行时长之和。

限制和注意事项

• 免费版的 entry_list、report、export_csv 和 invoice_summary 只能读取最近 7 天的数据。计时器和 条目本身没有数量限制，也不会被删除；只是免费调用可读取的时间范围较窄。
• 免费版支持为 2 个项目设置时薪；第三个设置了费率的项目需要 Pro。
• 所有 report 分组方式均可免费使用，包括按标签分组：标签总计是正确性修复，不是高级功能。group_by 本身为可选项；省略时会按货币显示未分组总额。
• 同一时间只能运行一个计时器。启动第二个计时器时，第一个会停止并记录，不支持并行计时。
• 没有提醒或空闲检测：如果忘记停止计时器，它会一直运行，直到你将其停止或启动另一个计时器。

故障排除

• npx 卡住或无法找到软件包：该软件包尚待发布到 npm。在发布前，请使用 .mcpb 捆绑包或上述克隆并构建的方式。
• 使用 .mcpb 捆绑包：它会直接安装到 Claude Desktop 中，无需单独配置路径。
• 使用克隆方式：运行 npm run build 后，服务二进制文件位于 servers/time-tracker/dist/index.js。将客户端的 command 指向 node，并将该文件的绝对路径作为唯一参数。
• Node 版本：需要 Node >= 18。运行 node -v 检查。
• 没有显示内容／静默失败：此服务只将日志写入 stderr，从不写入 stdout（stdout 保留给 MCP 协议使用）。 在 Claude Desktop 中，查看 Settings -> Developer -> 服务的日志文件；在 Claude Code 中，使用 --mcp-debug 运行，或查看启动它的终端。
• 无法识别 Pro 密钥：运行 license_status 查看服务识别的套餐，并确认 MCP_LICENSE_KEY 已在客户端启动 服务的同一进程中设置（而不只是设置在你的 shell 中）。

隐私

所有数据都保留在本地：条目存放在 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/time-tracker/data.json。 服务不会发起网络请求，不包含遥测功能，也无需账户。许可证密钥采用 Ed25519 签名，并由编译进软件包的公钥离线验证；激活无需互联网连接。

可配合使用

• mcp-invoice，将 invoice_summary 的输出直接转换为带编号的 PDF 发票。
• mcp-spreadsheet，使用 export_csv 导出 CSV，然后查询或调整其结构。
• mcp-price-tracker，如果你也会为客户采购物品，可以追踪这些物品的价格。
• office-suite，一次安装、一个配置项，即可使用套件中的所有关联服务。
• 指南：在 Claude Code 和 Cursor 中追踪可计费工时

常见问题

可以。三者都通过 stdio 使用 MCP，配置格式相同；无论使用哪个客户端，工具和数据文件都完全一致。

不会删除任何内容。条目会永久保留在 data.json 中；激活 Pro 前，它不会出现在 entry_list、report、export_csv 或 invoice_summary 的结果中。激活 Pro 后即可查看完整历史记录。

可以。货币按项目设置（也可以按条目设置，以覆盖项目默认值），所有总额都会按货币分组，报告不会将 EUR 和 USD 相加。

服务不会阻止时间重叠；它会记录你提供的信息。entry_edit 可用于事后修正错误。

不需要。此服务不会发起任何网络调用，包括许可证激活；许可证通过本地公钥验证。

许可证

MIT

整个套件共用一个业务资料

你的身份信息只需存储一次，路径为 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json， 套件中的每个服务都会读取这些信息：发票开具方、docx 信笺抬头、定期开具方、expense-tracker 的默认 VAT 税率、time-tracker 和 timezone 的本地时区，以及简历和合同的信笺抬头。使用 business_set（invoice 或 docx）设置一次即可，无需在其他地方重复填写。电子邮件地址只会从该资料或显式参数中获取；如果未存储地址，文档会显示 [add: email]，工具也会明确提示，而不会擅自填写地址。

常见问题

有没有免费的 MCP 时间追踪服务？

有。mcp.zovo.one 上的 time-tracker 服务是一款免费的 MCP 时间追踪服务，无需安装：在聊天中启动和停止计时器、按客户统计总时长并生成每周报告。与 SaaS 追踪工具（WebWork、TrackingTime）不同，它无需账户——粘贴托管 URL 即可使用。

如何在 Claude 中追踪时间？

连接 https://mcp.zovo.one/mcp/time-tracker（使用 mcp.zovo.one/mcp/connect 获取带令牌的 URL），然后说：“为 Acme 项目启动计时器。”之后用同样的方式停止计时器；只需提出要求，即可获取每周摘要。

将这些文档用作 MCP 服务

任何 MCP 客户端（Claude、Cursor、Windsurf、VS Code）都可以通过 GitMCP 直接读取此代码库的文档，无需安装：

• 文档 MCP URL： https://gitmcp.io/theluckystrike/mcp-time-tracker