UseHourly

UseHourly

供 AI 助手使用的免费开源时间追踪工具。 连接 Claude、ChatGPT、Cursor 或任何 MCP 助手，然后说“在 Acme 上记录 3 小时，再生成本周的工时表以供签核”。或者自己在几秒内记录一天的时间：输入 1.5、1:30 或 90m，按 Enter，完成。

在线体验： https://usehourly.app · 免费使用，无付费墙，无广告。

https://github.com/Zontak-LLC/usehourly/raw/main/public/landing/assistant-demo.mp4

功能介绍

• 快速录入。 选择项目，按你平时的说法输入时长，再添加备注。也可以按 Start 开始计时。
• 每周工时表。 在一个可编辑网格中查看所有项目和每天的记录。一次填写多天的工时，为某天添加更多记录，或将一条记录移到其他日期。
• 月历，显示各项目的汇总时长。
• 发票。 将可计费时长转换为 PDF 发票，跟踪已付款和未付款状态，并可随时重新下载。
• 年度汇总。 按季度和月份汇总工时、收入、已开票金额和已收款金额，可直接交给会计。
• 导出。 可将任意一周、一个月或自定义日期范围（例如 3 月 3 日至 4 月 20 日）的数据导出为 Excel，也可将所有内容打包成一个 zip：所有客户、全部时间记录。
• 先试用。 主页上的“使用示例数据试用”会打开一个填有一个月工作记录的临时账户。无需注册；如果喜欢，只需点击一次即可保留。
• 从 Toggl 或 Clockify 切换？ 在 Account 页面导入它们导出的 CSV 文件。系统会为你创建客户和项目，重复导入同一文件也不会添加重复内容。
• AI 优先：可与助手配合使用（MCP）。 任何 MCP 客户端（Claude、Cursor、VS Code、ChatGPT 或你自己的 Agent）都可以记录时间、启动计时器、生成客户工时表、创建私密签核链接并准备发票。详见下文。
• 免费计算器。 工时计算器：累加时长并换算为十进制小时数，无需账户。
• 你的数据归你所有。 用户之间相互隔离；你记录的所有内容都可以随时导出。

在任何 AI 助手中使用（MCP 服务）

UseHourly 在 https://usehourly.app/api/mcp 上运行远程 Model Context Protocol 服务（Streamable HTTP）。它提供 32 个工具，用于管理项目、客户、时间记录、计时器、工时表、发票和报告；每个工具都以你的身份运行，因此只能访问你自己的数据。在 Account > AI assistants 中创建令牌（只读或读写，并设置有效期），然后：

claude mcp add --transport http usehourly https://usehourly.app/api/mcp --header "Authorization: Bearer <your token>"

此示例适用于 Claude Code。其他客户端只需在 MCP 设置中配置 URL 和 Authorization: Bearer <token> 标头。

Cursor（~/.cursor/mcp.json）：

{ "mcpServers": { "usehourly": { "url": "https://usehourly.app/api/mcp", "headers": { "Authorization": "Bearer <your token>" } } } }

VS Code（.vscode/mcp.json）：

{ "servers": { "usehourly": { "type": "http", "url": "https://usehourly.app/api/mcp", "headers": { "Authorization": "Bearer <your token>" } } } }

对于只能运行本地（stdio）服务的客户端，例如 Claude Desktop，可使用发布在 npm 上的小型桥接程序（usehourly-mcp）：将命令设为 npx，参数设为 ["-y", "usehourly-mcp"]，并将 USEHOURLY_API_TOKEN 设为你的令牌。

然后提出请求：“记录昨天在 Acme 网站上的 2 小时工时”，或“为 Acme 制作一张 9 月份的发票”。

技术栈

Next.js 16（App Router） · React 19 · Tailwind CSS v4 · shadcn/ui · NextAuth v5（credentials） · tRPC v11 · Prisma 7 with Cloudflare D1 · Vitest · Biome · 使用 OpenNext 部署到 Cloudflare Workers。

本地运行

需要 Node 22+。

npm install                 # also runs `prisma generate`

cp wrangler.example.jsonc wrangler.jsonc   # then set account_id and database_id (see Deploy)

# .env.local and .dev.vars (keep the two in sync):
#   AUTH_SECRET=<a long random string, e.g. `openssl rand -base64 32`>
#   AUTH_URL=http://localhost:3028

npm run d1:migrate:local    # create the local D1 database
npm run dev                 # http://localhost:3028

在注册页面注册账户即可开始使用。

npm test                    # scenario tests (Vitest)
npx biome check             # lint and format
npx tsc --noEmit            # type check

部署

它运行在 Cloudflare Workers 上，并使用 D1 数据库：

1. 执行 cp wrangler.example.jsonc wrangler.jsonc，并填写你的 Cloudflare 账户 ID 和一个 D1 数据库 （npx wrangler d1 create usehourly-db）。wrangler.jsonc 已加入 Git 忽略列表，因此你的 ID 不会进入代码库。
2. 在 .env.production.local 中填写你的公开地址：NEXT_PUBLIC_APP_URL=https://app.example.com （该值会打包进构建产物），并在 wrangler.jsonc 中将相同的值设为 AUTH_URL。
3. npm run d1:migrate:remote
4. npx wrangler secret put AUTH_SECRET
5. npm run deploy

邮件（可选）

密码重置和邮件确认需要邮件服务。UseHourly 通过 Resend 发送邮件：在该平台验证你的发件域名，然后在 Worker 上设置两个值：

npx wrangler secret put RESEND_API_KEY
npx wrangler secret put EMAIL_FROM        # for example: UseHourly <[email protected]>

不设置这些值，应用仍会照常运行，而忘记密码页面会提示尚未配置邮件服务。

从 CircleCI 部署

.circleci/config.yml 会在每次推送时运行检查，并在 main 分支上应用 D1 迁移并部署。部署令牌是机密信息，因此不要将其放在项目设置中：创建一个名为 usehourly-production 的 context（Organization Settings > Contexts），添加表达式限制 pipeline.git.branch == "main"，并将令牌放入其中。只有 main 分支上的部署作业可以读取它。

Context 变量	值
CLOUDFLARE_API_TOKEN	具有 Workers Scripts: Edit 和 D1: Edit 权限的令牌

在 CircleCI 项目设置中添加以下环境变量：

变量	值
CLOUDFLARE_ACCOUNT_ID	你的 Cloudflare 账户 ID
D1_DATABASE_ID	你的 D1 数据库 ID
APP_URL	你的公开地址，例如 https://app.example.com

可选：WORKER_NAME、D1_DATABASE_NAME、CUSTOM_DOMAIN。AUTH_SECRET 保留为 Worker 机密（执行一次 npx wrangler secret put AUTH_SECRET）；CI 不会接触它。scripts/ci-wrangler-config.mjs 会根据这些变量生成 wrangler.jsonc，因此代码库中不会存放账户 ID。

支持

UseHourly 免费。如果它为你节省了时间，可以在 GitHub 上赞助它。

赞助者

感谢所有帮助 UseHourly 保持免费的支持者：

成为第一位：在 GitHub 上赞助 UseHourly。

致谢与许可证

基于 Mohammed Arham Khan 的优秀模板 next-shadcn-admin-dashboard 构建。

根据 MIT License 发布。代码是开源的；名称“UseHourly”和其徽标不属于许可证范围。