atimelogger-mcp

ATimeLogger MCP 服务

一个独立的 MCP（Model Context Protocol）服务，可向 AI 助手开放 ATimeLogger REST API——通过 stdio 在本地运行（Claude Desktop / Claude Code / OpenAI Codex），或作为连接器远程运行（浏览器中的 claude.ai、Claude 移动应用、ChatGPT）。范围：活动（开始/停止/暂停/记录）、报告/历史记录和活动类型。

同一软件包还会安装 atimelogger-cli——一个只读 JSON 命令行工具，无需 AI 助手即可使用。可在 cron 任务、状态栏和 Shell 管道中使用；它与服务共用内部功能（模糊匹配类型名称、时段词汇、正确处理夏令时的时区），但完全独立运行。库入口则适用于第三种情况：在你自己的代码中进程内调用 ATimeLogger。

设置

需要 Node 20+。

1. 在 ATimeLogger Web 应用中生成个人访问令牌：Settings → API Tokens → Generate token。令牌值（以 atl_pat_ 开头）只会显示一次——请立即复制。你可以随时在同一页面撤销令牌。

2. 注册服务。无需安装或构建步骤——首次运行时，npx 会获取已发布的软件包：

Claude Code——一行命令：

claude mcp add atimelogger \
  -e ATL_TOKEN=atl_pat_... \
  -- npx -y atimelogger-mcp

Claude Desktop——将以下 JSON 块合并到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），然后重启 Claude Desktop：

{
  "mcpServers": {
    "atimelogger": {
      "command": "npx",
      "args": ["-y", "atimelogger-mcp"],
      "env": {
        "ATL_TOKEN": "atl_pat_..."
      }
    }
  }
}

OpenAI Codex（CLI、IDE 扩展或 ChatGPT 桌面应用的 Codex 模式）——同样只需一行命令；三个 Codex 入口共用此配置：

codex mcp add atimelogger --env ATL_TOKEN=atl_pat_... -- npx -y atimelogger-mcp

等效的 ~/.codex/config.toml 配置块：

[mcp_servers.atimelogger]
command = "npx"
args = ["-y", "atimelogger-mcp"]
env = { "ATL_TOKEN" = "atl_pat_..." }

Codex 中的 MCP 支持不受套餐限制——任何包含 Codex 的 ChatGPT 订阅均可使用，也可以使用普通 API 密钥。（在 ChatGPT 网页/移动应用中使用这些工具属于另一种接入方式——请参阅下文的从 ChatGPT 连接。）

从源代码运行

你也可以克隆并构建，而不是使用已发布的软件包：

git clone https://github.com/zaplitny/atimelogger-mcp && cd atimelogger-mcp
npm install
npm run build
npm run setup        # paste the token, verifies it, prints registration snippets pointing at the local build

故障排查：任何工具返回 401 都表示令牌无效、已过期或已撤销——请在 Settings → API Tokens 中生成新令牌，并更新 MCP 配置中的 ATL_TOKEN。

还没有令牌？服务也可以在没有 ATL_TOKEN 的情况下以仅文档模式启动：app_help 工具（官方应用文档）可正常使用，因此你可以先询问助手 ATimeLogger 功能的工作方式，再设置 API 访问；在配置令牌之前，时间追踪工具会返回设置说明。

工具

工具	用途
get_current_status	正在运行/已暂停的活动及已用时间
list_activity_types	以分组树形式显示活动类型名称（其他工具的名称来源）
start_activity	按类型名称开始活动；可选回溯设置时间（墙上时钟时间 at 或 started_minutes_ago）
stop_activity	停止当前活动（如果只有一个活动正在进行，则名称可选）；支持相同的回溯设置时间选项
pause_resume_activity	暂停或恢复
log_interval	追溯记录已完成的条目（墙上时钟时间，可选备注/标签）
update_activity	更改现有条目（正在运行或过去的条目）的备注/标签，不修改其时间
time_report	某个时段的按类型汇总统计（today、this_week、last_month……或明确日期）
list_intervals	按天分组的原始历史记录，分页显示，日期范围最多 100 天
app_help	官方应用文档（atimelogger.pro/docs）——助手会查找应用功能（目标、小组件、同步、导出等）的工作方式，而不是凭空猜测

工具接受便于人类阅读的类型名称（采用模糊匹配）；内部 ID 也会通过工具输出和参数传递，以便精确指定目标，但不会显示给用户。时长以 "2h 15m" 字符串返回；时间按用户的 ATimeLogger 时区显示，除非提供了 timezone 参数。

使用示例

注册服务后，可以对助手说：

计时器

“开始记录工作” · “停止计时器” · “暂停阅读，我 10 分钟后回来” · “我现在在记录什么？”

回溯记录 — 忘记按开始或停止时：

“开始记录 Development——我其实 11:30 就开始了” · “停止工作，我 20 分钟前就结束了” · “我从 14:00 起一直在开会，记录一下”

记录过去的活动

“记录昨天 9 点到 11 点的 2 小时阅读” · “添加一条上周六早上的健身记录，时长 90 分钟，标签设为 ‘legs’” · “我从 23:30 睡到 7:15，记录一下”

为现有记录添加注释

“给当前计时器添加备注：正在审阅 Q3 报告” · “给今天早上的工作时段添加 ‘client-x’ 标签” · “更新昨天的会议记录——那是架构同步会”

报告与历史记录

“我这一周都做了些什么？” · “我 6 月工作了多久？按周细分” · “比较我这个月和上个月的睡眠情况” · “显示我今天记录的所有内容” · “上周哪天的 Development 时间最长？”

了解应用 — 根据官方文档回答，而非凭空猜测：

“目标是如何运作的？” · “为什么同步没有获取昨天的记录？” · “组和类型有什么区别？” · “我可以导出为 CSV 吗？” · “如何编辑记录的时间？”

组合操作 — 助手会自行串联工具：

“停止当前正在运行的项目，然后开始工作” · “从上一条记录结束的时间继续——从那个时间开始记录 Development” · “填上昨天午餐和会议之间的空档，记录为阅读”

活动名称会与您自己的类型列表进行模糊匹配，因此“开始 dev”会找到“Development”；如果名称有歧义，助手会询问。

命令行界面

atimelogger-cli 随同一软件包安装，可独立运行——无需 MCP 客户端、助手或除同一个 ATL_TOKEN 以外的 API 密钥。它是一个只读 JSON 命令行工具，适用于不便使用 MCP 的脚本和自动化场景（cron 任务、状态栏、Shell 管道），并复用了 MCP 工具所依赖的内部功能：模糊类型名称、时间段词语、正确处理夏令时的时区和易读时长。

export ATL_TOKEN=atl_pat_...
npx -y -p atimelogger-mcp atimelogger-cli status
atimelogger-cli report --period this_week --type work
atimelogger-cli intervals --period yesterday --tag gym --compact | jq .

命令包括：status、types、report、intervals，以及 doctor——运行 atimelogger-cli --help 查看所有选项。当出现问题时，首先运行 doctor：它会检查令牌是否存在及其格式是否正确、主机是否可访问、令牌是否仍可通过身份验证，以及账户是否有可跟踪的类型；它会指出出问题的环节，而不是让你猜测。状态异常时，它会以代码 1 退出，且绝不会回显令牌。输出始终为 JSON（默认采用易读格式，使用 --compact 可输出单行），并具有稳定的键：时长同时包含易读字符串和原始 seconds，分页状态用布尔值 has_more 表示，结果为空时返回 []，而不会省略该键——因此 jq 管道不会在没有记录的一天出错。错误会以 {"error": "..."} 的形式输出到 stderr，并以退出代码 1 退出（用法错误时为 2，包括无法解析的 --type）。该命令行工具不会开始、停止或编辑任何内容——写入操作仍由 MCP 服务处理，并由人在流程中把关；通过 cron 脚本写入容易因重试而出错，也可能破坏你的时间线。

库的使用（实验性）

该包还导出了以任务为核心的接口，因此长时间运行的进程可以在进程内调用 ATimeLogger，而不必每次请求都启动一个二进制文件——适用于守护进程、机器人、编辑器插件，或任何希望在不使用 MCP 传输的情况下，享受各种便利功能（模糊类型名称、周期词语、正确处理夏令时的时区、人性化时长）的场景。

import { createClient, clientFromEnv } from "atimelogger-mcp";

const atl = createClient({ token });    // credentials passed explicitly
// …or, for the single-account case, read ATL_TOKEN + ATL_BASE_URL:
// const atl = clientFromEnv();

// reads
const { active } = await atl.status();
const { duration, seconds, by_type } = await atl.report({ period: "this_week", type_names: ["work"] });
const { days, has_more } = await atl.intervals({ period: "yesterday" });

// writes
await atl.start({ type_name: "development", started_minutes_ago: 10 });
await atl.stop();                                   // name optional if one is active
await atl.pauseResume({ action: "pause" });
await atl.log({ type_name: "reading", from: "2026-08-05 21:00", to: "2026-08-05 22:30" });
await atl.update({ activity_id, comment: "architecture sync" });

await atl.api.get("/api/…");                        // escape hatch for anything unwrapped

优先使用 clientFromEnv()，而不是手动编写 createClient({ token: process.env.ATL_TOKEN })——后者会忽略 ATL_BASE_URL，并悄无声息地将请求发送到生产环境。与 MCP 服务和 CLI 不同，如果未配置令牌，它会抛出异常，而不是退出宿主进程。

写入操作属于客户端的一部分，而不是让你基于 api 自行组装，因为操作顺序很重要：update 会执行读取-修改-写入，因为直接使用原始 PUT 会软删除负载中缺失的每个时间区间，悄无声息地销毁条目已跟踪的时间。（CLI 出于另一个原因保持只读——为了应对无人值守的 Shell 重试，而不是程序调用。）

返回结果都有完整的类型（CurrentStatus、TimeReport、IntervalsPage、StartedActivity 等），除非类型标记为可选，否则每个字段都会存在——days、active 和 by_type 在没有数据时是空数组，而不是缺失的键，因此对空结果进行解构是安全的。时长同时提供人性化字符串和原始 seconds。错误也有类型：UsageError（参数错误或无法解析类型名称）、ApiError（服务端返回失败响应，包含 .status）、NetworkError（请求未能到达，会保留原始错误作为 .cause）。

每个客户端都有自己的 HTTP 客户端和缓存，因此一个进程中可以同时使用多个账户。通过覆盖 fetch，可以轻松使用测试夹具进行测试，无需访问网络：

const atl = createClient({ token: "test", baseUrl: "https://example.test", fetch: fakeFetch });

app_help 不属于此接口——它会从公共文档网站获取回答，而不是从账户获取，因此仍作为 MCP 工具提供。

这些客户端完全在进程内运行——没有守护进程、没有持久化状态，也没有在不同调用之间共享任何内容；要让缓存保持热状态，就需要让进程持续运行。导入库时不会读取环境变量。由于该包仍处于 0.x 版本，因此功能具有实验性：签名可能会在次版本发布时发生变化，如果你依赖这些接口，请锁定精确版本。

远程服务（自定义连接器）

除了上述本地 stdio 配置外，该服务还可以作为远程 MCP 服务运行，并以自定义连接器的方式连接到 Claude——也可以通过开发者模式（C 节）连接到 ChatGPT。如果你想从浏览器中的 claude.ai、Claude 移动应用，或 ChatGPT 网页版／移动应用访问 ATimeLogger 数据，而这些环境不支持本地 stdio 服务，就可以使用此方式。

这里面向两类用户：只想连接到正在运行的端点的用户，以及想要自托管服务的用户。

A. 连接到远程端点

如果你有正在运行的实例的 HTTPS URL（例如，根据 B 节自行托管的实例）：

1. 在浏览器中打开 claude.ai（桌面或移动设备均可）。一次性的“添加”步骤需在网页界面中完成；添加后，连接器也会显示在移动应用中。
2. 前往 Settings → Connectors → Add custom connector。
3. 输入名称（例如 ATimeLogger）和以 /mcp 结尾的服务 URL：

   https://your-host.example.com/mcp
   

4. 点击 Add。
5. 在任意聊天中，打开 + 菜单 → Connectors，然后启用该连接器。

之后像平常一样与 Claude 对话——“我现在在跟踪什么？”，“我的这一周都花在哪了？”等（参见使用示例）。在移动设备上，只要为当前对话启用了连接器，使用方式也相同。

关于 Claude 如何连接到你的服务的说明。 自定义连接器是从 Anthropic 的云基础设施连接到你的服务，而不是从你自己的设备连接——即使在移动应用和 Claude Desktop 中也是如此。你的端点必须能通过公共互联网访问。即使你能从自己的机器访问，在 localhost 上、VPN 后，或被防火墙阻止的服务也无法连接。

B. 自托管远程端点

该服务使用 stdio 通信，因此若要通过 HTTPS 公开访问，需要在前面放置一个小型代理，通过 Streamable HTTP 提供服务，然后使用反向代理终止 TLS。以下是一种可用的配置：

1. 在 Docker 中通过 HTTP 代理运行服务。 主机只需要 Docker——无需检出源码，也无需安装 Node。该镜像会拉取已发布的 npm 包和 mcp-proxy，后者会通过 Streamable HTTP 提供 stdio 服务：

FROM node:22-slim
RUN npm i -g atimelogger-mcp mcp-proxy
EXPOSE 8080
CMD ["mcp-proxy", "--port", "8080", "--", "atimelogger-mcp"]

如果希望重新构建时结果可复现，可以固定版本（npm i -g [email protected]）；以后升级时，使用 --no-cache 重新构建（或更新固定版本），然后重新创建容器。

构建并运行服务，仅绑定到 localhost，并将令牌作为环境变量传入：

docker build -t atimelogger-mcp .
docker run -d --name atimelogger-mcp \
  -p 127.0.0.1:9095:8080 \
  --restart unless-stopped \
  -e ATL_TOKEN=atl_pat_your_token_here \
  atimelogger-mcp

在本地确认服务已启动（直接发送 GET 会返回 400 Bad Request——这是预期行为，表示端点正在监听，但拒绝不完整的握手）：

curl -i http://127.0.0.1:9095/mcp

2. 在前面配置 TLS 反向代理。 以下是 HTTPS 服务块中的 nginx location 块示例。流式传输相关指令（proxy_buffering off、较长的 proxy_read_timeout）很重要——缺少它们，连接就会停滞：

location /mcp {
    proxy_pass http://127.0.0.1:9095/mcp;
    proxy_http_version 1.1;

    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # streaming essentials
    proxy_set_header Connection '';
    proxy_buffering  off;
    proxy_cache      off;
    proxy_read_timeout  3600s;
    chunked_transfer_encoding on;
}

sudo nginx -t && sudo systemctl reload nginx

现在，你的公共端点为 https://your-host.example.com/mcp——按照 A 节的说明，将其添加为 Custom Connector。

3. 连接 Claude 前先进行测试（可选）。 MCP Inspector 可以独立验证该端点：

npx @modelcontextprotocol/inspector

将传输类型设为 Streamable HTTP，输入 URL，并确认握手成功且工具列表已显示。

安全提示——公开之前请先阅读。 远程服务通过容器中内置的单个 ATL_TOKEN 进行身份验证，因此，任何能够访问该 URL 的人都可以代表你操作 ATimeLogger 账户。MCP 层没有针对单个用户的登录机制。如果选择自托管：

• 保持端点私有（不要公开 URL），或在端点前添加身份验证检查（例如，在 nginx 中要求提供特定标头或进行基本身份验证）。
• 仅将容器绑定到 127.0.0.1（如上所示），避免直接暴露原始 HTTP 端口——nginx 应是唯一的公共入口。
• 将令牌视同密码；如果令牌泄露，请前往 Settings → API Tokens 轮换令牌。

C. 从 ChatGPT 连接（Developer Mode）

同一远程端点也可以通过 Developer Mode（付费方案）作为自定义 MCP 应用在 ChatGPT 网页应用中使用。设置的位置和操作流程可能会随时间变化——请参阅官方指南：https://developers.openai.com/api/docs/guides/developer-mode。简而言之：

1. 在 ChatGPT 设置中启用 Developer mode（具体位置请参阅指南）。
2. 为以 /mcp 结尾的服务 URL 创建新的应用／连接器，并将身份验证设为 None（ATimeLogger 令牌保存在服务端；请参阅上方的安全提示）。
3. 在聊天中启用该应用，然后像平常一样提问——“我现在在追踪什么？”，“记录昨天晚上 9 点到 11 点的 2 小时阅读时间”。

注意：

• 只需在 网页 应用中设置一次；之后，该连接器也可在 ChatGPT 移动应用中使用。
• ChatGPT 会从 OpenAI 的基础设施发起连接，因此端点必须可通过公共网络访问——这与 Claude 自定义连接器的要求相同。
• 默认情况下，执行写入操作（启动／停止计时器、记录条目）前，ChatGPT 会要求确认。
• 方案、地区和功能限制可能适用，且会随时间变化——请查阅官方文档了解当前情况。（不要将 Developer Mode 与 ChatGPT 仅支持 search／fetch 的 Deep Research 连接器混淆——此服务提供操作类工具，因此应使用 Developer Mode。）

限制

• start_activity 无法附加评论（底层的开始端点只接受类型和时间）；之后可使用 update_activity 添加评论，或使用 log_interval 追溯记录带有评论／标签的条目。
• 只能编辑现有条目的评论和标签（update_activity）；无法更改时间段，也无法删除条目——请使用 ATimeLogger 应用执行这些操作（助手可通过 app_help 说明操作方法）。
• 后端将历史记录请求限制为最多 100 天。