hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

ActivityWatch MCP 服务器

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

特征

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

安装

您可以从 npm 安装 ActivityWatch MCP 服务器，也可以自行构建。

从 npm 安装（即将推出）

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

# Or install locally
npm install activitywatch-mcp-server

从源代码构建

克隆此存储库：
git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git cd activitywatch-mcp-server
安装依赖项：
npm install
构建项目：
npm run build

先决条件

ActivityWatch已安装并正在运行
Node.js（v14 或更高版本）
Claude 桌面版（或任何其他 MCP 客户端）

用法

与 Claude for Desktop 一起使用

打开您的 Claude for Desktop 配置文件：
- Windows： %APPDATA%\Claude\claude_desktop_config.json
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
添加 MCP 服务器配置：

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

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

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

重启 Claude 桌面版
在 Claude 的界面中查找 MCP 图标以确认其正常工作

示例查询

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

列出所有存储桶：“我有哪些 ActivityWatch 存储桶？”
获取应用程序使用情况摘要：“你能告诉我今天我使用最多的应用程序是哪些吗？”
查看浏览历史记录：“我今天在哪些网站上花费的时间最多？”
检查生产力：“我今天在生产力应用程序上花了多少时间？”
查看设置：“我的 ActivityWatch 设置是什么？”或“您能在 ActivityWatch 中检查特定设置吗？”

可用工具

列表桶

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

参数：

type （可选）：按类型过滤存储桶（例如“window”、“web”、“afk”）
includeData （可选）：在响应中包含存储桶数据

运行查询

使用 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数组中的每个项目都是包含所有语句的完整查询

获取事件

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

参数：

bucketId ：从中获取事件的存储桶的 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;

配置

服务器默认通过http://localhost:5600连接到 ActivityWatch API。如果您的 ActivityWatch 实例运行在其他主机或端口上，您可以在源代码中修改此设置。

故障排除

ActivityWatch 未运行

如果 ActivityWatch 未运行，服务器将显示连接错误。请确保 ActivityWatch 正在运行并且可以通过http://localhost:5600访问。

查询错误

如果您遇到查询错误：

检查查询语法
确保存储桶 ID 正确
验证时间段是否包含数据
查看 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;"]
}