内容
# ATimeLogger MCP 服务器
一个独立的 MCP（模型上下文协议）服务器，通过 stdio 向 Claude Desktop / Claude Code 公开 ATimeLogger REST API。范围：活动（开始/停止/暂停/记录）、报告/历史记录和活动类型。
## 设置
需要 Node 20+。
1. 在 ATimeLogger 网页应用中生成 **个人访问令牌**：**设置 → API 令牌 → 生成令牌**。该值（以 `atl_pat_` 开头）仅显示 **一次** — 立即复制。你可以随时在同一页面撤销该令牌。
2. 构建服务器并注册它：
```bash
npm install
npm run build
npm run setup # 粘贴令牌，验证它，打印注册命令
```
设置脚本为两个客户端打印即用注册代码段：
**Claude Code** — 一行命令：
```bash
claude mcp add atimelogger \
-e ATL_TOKEN=atl_pat_... \
-- node /绝对路径/to/atimelogger-mcp/dist/index.js
```
**Claude Desktop** — 一个 JSON 块，合并到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows），然后重启 Claude Desktop：
```json
{
"mcpServers": {
"atimelogger": {
"command": "node",
"args": ["/绝对路径/to/atimelogger-mcp/dist/index.js"],
"env": {
"ATL_TOKEN": "atl_pat_..."
}
}
}
}
```
服务器默认针对生产环境（`https://app.atimelogger.pro`）— 无需配置 URL。要针对不同的后端工作，请显式设置 `ATL_BASE_URL`：将 `--url <base-url>` 传递给设置脚本（或设置环境变量），它将在打印的代码段中包含 `ATL_BASE_URL`。在指向 MCP 的 **相同** 服务器的网页 UI 中生成令牌。
故障排除：来自任何工具的 401 表示令牌无效、已过期或已被撤销 — 在 **设置 → API 令牌** 中生成新的令牌，并更新 MCP 配置中的 `ATL_TOKEN`。
## 工具
| 工具 | 用途 |
|---|---|
| `get_current_status` | 运行/暂停活动及已用时间 |
| `list_activity_types` | 作为组树（其他工具名称的来源）的活动类型名称 |
| `start_activity` | 按类型名称开始；可选的追溯（`at` 挂钟时间或 `started_minutes_ago`） |
| `stop_activity` | 停止活动活动（如果只有一个活动，则名称可选）；相同的追溯选项 |
| `pause_resume_activity` | 暂停或恢复 |
| `log_interval` | 追溯记录已完成的条目（挂钟时间，可选注释/标签） |
| `time_report` | 按类型聚合的某段时间（`today`、`this_week`、`last_month`，... 或明确的日期）统计数据 |
| `list_intervals` | 按天分组的原始历史记录，分页，最多 100 天范围 |
工具接受人类可读的类型名称（模糊匹配）；内部 ID 也通过工具输出和参数进行精确目标定位，但从不显示给用户。持续时间以 `"2h 15m"` 字符串形式返回；除非提供 `timezone` 参数，否则时间均显示为用户的 ATimeLogger 时区。
## 使用示例
服务器注册后，你可以对助手说的事情：
**计时器**
> "开始跟踪工作" · "停止计时器" · "暂停阅读，我 10 分钟后回来" · "我现在正在跟踪什么？"
**追溯** — 忘记按开始或停止：
> "开始开发 — 我实际上在 11:30 开始的" · "停止工作，我 20 分钟前完成了" · "我从 14:00 开始开会，记录它"
**记录过去的活动**
> "记录昨晚 9 点到 11 点的 2 小时阅读时间" · "为上周六上午添加一个健身会话，持续 90 分钟，标记为 '腿'" · "我从 23:30 睡到 7:15，记录它"
**报告和历史记录**
> "我的一周去哪了？" · "我六月份工作了多少时间，按周分解？" · "比较这个月和上个月的睡眠时间" · "显示我今天跟踪的所有内容" · "哪一天的开发时间最多？"
**组合** — 助手自行链接工具：
> "停止正在运行的任何内容并开始工作" · "从上一个条目结束的地方继续 — 从那个时间开始开发" · "用阅读内容填充昨天的午餐和会议之间的空白"
活动名称与您自己的类型列表进行模糊匹配，因此 "start dev" 可以找到 "Development"；当名称不明确时，助手会询问。
## 限制
- `start_activity` 无法附加注释（底层启动端点仅接受类型和时间）；请使用 `log_interval` 记录具有注释/标签的条目。
- 现有条目不允许编辑（服务器端更新 API 不完整）。
- 历史记录请求受到后端限制，最大范围为 100 天。
MCP 市场