ActivityWatch MCP 服务器

一个模型上下文协议 (MCP) 服务器，用于连接 ActivityWatch，允许像 Claude 这样的 LLM 与你的时间跟踪数据进行交互。

功能

• 列出存储桶 (List Buckets)：查看所有可用的 ActivityWatch 存储桶

• 运行查询 (Run Queries)：执行强大的 AQL (ActivityWatch 查询语言) 查询

• 获取原始事件 (Get Raw Events)：直接从任何存储桶中检索事件

• 获取设置 (Get Settings)：访问 ActivityWatch 配置设置

Related MCP server: Paprika SQL MCP Server

安装

你可以通过 npm 安装 ActivityWatch MCP 服务器，也可以自行构建。

通过 npm 安装 (即将推出)

# Global installation
npm install -g activitywatch-mcp-server

# Or install locally
npm install activitywatch-mcp-server

从源码构建

1. 克隆此仓库：

   git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
   cd activitywatch-mcp-server

2. 安装依赖：

   npm install

3. 构建项目：

   npm run build

先决条件

• 已安装并运行 ActivityWatch

• Node.js (v14 或更高版本)

• Claude for Desktop (或任何其他 MCP 客户端)

使用方法

在 Claude for Desktop 中使用

1. 打开你的 Claude for Desktop 配置文件：

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. 添加 MCP 服务器配置：

   {
   "mcpServers": {
       "activitywatch": {
       "command": "activitywatch-mcp-server",
       "args": []
       }
   }
   }

   如果你是从源码构建的，请使用：

   {
   "mcpServers": {
       "activitywatch": {
       "command": "node",
       "args": ["/path/to/activitywatch-mcp-server/dist/index.js"]
       }
   }
   }

3. 重启 Claude for Desktop

4. 在 Claude 界面中查找 MCP 图标以确认其正在运行

在 Linux 上使用无根 podman 容器配合 Gemini CLI

请确保先使用以下命令构建镜像：

version=$(npm pkg get version | tr -d '"')
podman build . -t activitywatch-mcp-server:${version}

此示例使用了 Activity Watch 在 127.0.0.1 上不可用的覆盖设置（请参阅下一节）。如果不需要，可以省略 AW_API_BASE 环境变量。

{
  "mcpServers": {
    "activitywatch-mcp-server": {
      "command": "/usr/bin/podman",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--userns=keep-id",
        "-e",
        "AW_API_BASE",
        "localhost/activitywatch-mcp-server:1.2.1"
      ],
      "env": {
        "AW_API_BASE": "http://mydesktop.local:5600/api/0"
      }
    }
  }
}

覆盖 ActivityWatch 服务器主机/端口

如果你想从 Windows Linux 子系统 (WSL) 内部运行此 MCP 服务器（例如在容器内），则在 Windows 上运行的 AW 服务器将无法在 127.0.0.1 上访问。要覆盖标准 localhost 连接，请使用环境变量 AW_API_BASE 或 --aw-api-base 标志，如下所示：

# Using environment variable
export AW_API_BASE=http://mydesktop.local:5600/api/0
node dist/index.js

# Or using command-line flag
node dist/index.js --aw-api-base=http://mydesktop.local:5600/api/0

注意：AW 服务器可能会对用于连接它的名称比较挑剔，但它会接受与运行它的计算机名称匹配并带有 .local 后缀的名称。

查询示例

以下是一些你可以在 Claude 中尝试的查询示例：

• 列出所有存储桶：“我有哪些 ActivityWatch 存储桶？”

• 获取应用程序使用摘要：“你能告诉我今天我使用最多的应用程序是什么吗？”

• 查看浏览历史：“我今天在哪些网站上花费的时间最多？”

• 检查生产力：“我今天在生产力应用程序上花费了多少时间？”

• 查看设置：“我的 ActivityWatch 设置是什么？”或“你能检查一下 ActivityWatch 中的特定设置吗？”

可用工具

list-buckets

列出所有可用的 ActivityWatch 存储桶，并支持可选的类型过滤。

参数：

• type (可选)：按类型过滤存储桶（例如：“window”、“web”、“afk”）

• includeData (可选)：在响应中包含存储桶数据

run-query

在 ActivityWatch 的查询语言 (AQL) 中运行查询。

参数：

• timeperiods：要查询的时间段，格式为字符串数组。对于日期范围，请使用格式：["2024-10-28/2024-10-29"]

• query：ActivityWatch 查询语言中的查询语句数组，其中每一项都是一个完整的查询，语句之间用分号分隔

• name (可选)：查询名称（用于缓存）

重要提示：每个查询字符串应包含一个完整的查询，其中多个语句用分号分隔。

示例请求格式：

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

请注意：

• timeperiods 应具有预先格式化的带斜杠的日期范围

• query 数组中的每一项都是包含所有语句的完整查询

get-events

从 ActivityWatch 存储桶获取原始事件。

参数：

• bucketId：要从中获取事件的存储桶 ID

• start (可选)：ISO 格式的开始日期/时间

• end (可选)：ISO 格式的结束日期/时间

• limit (可选)：要返回的最大事件数

get-settings

从服务器获取 ActivityWatch 设置。

参数：

• key (可选)：获取特定的设置键，而不是所有设置

查询语言示例

ActivityWatch 使用一种简单的查询语言。以下是一些常见的模式：

// Get window events
window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;

// Get only when not AFK
afk_events = query_bucket(find_bucket("aw-watcher-afk_"));
not_afk = filter_keyvals(afk_events, "status", ["not-afk"]);
window_events = filter_period_intersect(window_events, not_afk);
RETURN = window_events;

// Group by app
window_events = query_bucket(find_bucket("aw-watcher-window_"));
events_by_app = merge_events_by_keys(window_events, ["app"]);
RETURN = sort_by_duration(events_by_app);

// Filter by app name
window_events = query_bucket(find_bucket("aw-watcher-window_"));
code_events = filter_keyvals(window_events, "app", ["Code"]);
RETURN = code_events;

配置

服务器默认连接到 http://localhost:5600 的 ActivityWatch API。如果你的 ActivityWatch 实例运行在不同的主机或端口上，你可以按照上述“覆盖 ActivityWatch 服务器主机/端口”部分中的说明进行覆盖。

故障排除

ActivityWatch 未运行

如果 ActivityWatch 未运行，服务器将显示连接错误。请确保 ActivityWatch 正在运行，并且可以在指定的主机/端口地址（除非你已覆盖它，否则为 http://localhost:5600）访问。

查询错误

如果你遇到查询错误：

1. 检查你的查询语法

2. 确保存储桶 ID 正确

3. 验证时间段内包含数据

4. 查看 ActivityWatch 日志以获取更多详细信息

Claude/MCP 查询格式问题

如果 Claude 在通过此 MCP 服务器运行查询时报告错误，很可能是由于格式问题。请确保你的查询在提示词中遵循此确切格式：

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["events = query_bucket('aw-watcher-window_UNI-qUxy6XHnLkk'); RETURN = events;"]
}

常见问题：

• 时间段格式不正确（应在数组内的单个字符串中为“开始/结束”）

• 查询语句被拆分为单独的数组元素，而不是组合在一个字符串中

最常见的格式问题

最常见的错误是 Claude 将每个查询语句拆分为自己的数组元素，如下所示：

{
  "query": [
    "browser_events = query_bucket('aw-watcher-web');",
    "afk_events = query_bucket('aw-watcher-afk');",
    "RETURN = events;"
  ],
  "timeperiods": ["2024-10-28/2024-10-29"]
}

这是错误的。相反，所有语句都应位于数组内的单个字符串中：

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["browser_events = query_bucket('aw-watcher-web'); afk_events = query_bucket('aw-watcher-afk'); RETURN = events;"]
}

提示 Claude 时

在提示 Claude 时，请明确格式并使用示例。例如，说：

“运行一个查询，其中 timeperiods 为 ["2024-10-28/2024-10-29"]，查询为 ["statement1; statement2; RETURN = result;"]。重要提示：确保所有查询语句都在数组内的单个字符串中，而不是拆分为单独的数组元素。”

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT