ActivityWatch MCP

活动监视MCP服务器

连接到的模型上下文协议（MCP）服务器 活动观察，允许像克劳德这样的法学硕士 与您的时间跟踪数据进行交互。

特性

• 列出Buckets：查看所有可用的ActivityWatch bucket
• 运行查询：执行强大的AQL（ActivityWatch查询语言）查询
• 获取原始事件：直接从任何存储桶中检索事件
• 获取设置：访问ActivityWatch配置设置

安装

您可以从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

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

先决条件

• 活动观察 已安装并正在运行
• Node.js（v14或更高版本）
• Claude for Desktop（或任何其他MCP客户端）

用法

使用Claude for Desktop

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

- 窗户： %APPDATA%\Claude\claude_desktop_config.json - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

1. 添加MCP服务器配置：

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

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

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

1. 重新启动桌面版的Claude

1. 在Claude的界面中查找MCP图标，以确认其正常工作

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

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

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

此示例使用了“活动监视”的覆盖，该覆盖在上不可用 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子系统内部运行此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中的具体设置？"

可用工具

列出bucket

列出所有可用的ActivityWatch bucket，并提供可选的类型筛选。

参数：

• type （可选）：按类型过滤桶（例如，“窗口”、“网络”、“afk”）
• includeData （可选）：在响应中包含存储桶数据

运行查询

使用ActivityWatch的查询语言（AQL）运行查询。

参数：

• timeperiods：查询格式化为字符串数组的时间段。日期

范围，使用格式： ["2024-10-28/2024-10-29"]

• query：ActivityWatch查询语言中的查询语句数组，其中每个

item是一个完整的查询，语句之间用分号分隔

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

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

请求格式示例：

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

请注意：

• timeperiods 应具有带斜线的预格式化日期范围
• 中的每个项目 query 数组是一个包含所有语句的完整查询

获取事件

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

参数：

• bucketId：从中获取事件的bucket的ID
• start （可选）：ISO格式的开始日期/时间
• end （可选）：ISO格式的结束日期/时间
• limit （可选）：要返回的最大事件数

获取设置

从服务器获取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;

配置

服务器连接到位于的ActivityWatch API http://localhost:5600 通过 违约。如果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时，要非常明确地说明格式并使用示例。对于 例如，说：

“按以下方式运行包含时间段的查询 ["2024-10-28/2024-10-29"] 并查询为 ["statement1; statement2; RETURN = result;"]重要提示：确保所有查询 语句位于数组中的单个字符串中，不拆分为单独的字符串 阵列元素。"

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院