ActivityWatch MCP 服务器

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

<a href="https://glama.ai/mcp/servers/msnzvab06f"> <img width="380" height="200" src="https://glama.ai/mcp/servers/msnzvab06f/badge" alt="ActivityWatch Server MCP server" /> </a>

功能

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

安装

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

通过 npm 安装 (即将推出)

# 全局安装
npm install -g activitywatch-mcp-server

# 或者本地安装
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 图标，以确认它正在工作

示例查询

以下是一些你可以在 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 使用一种简单的查询语言。 以下是一些常见的模式:

// 获取窗口事件
window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;

// 仅在非 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;

// 按应用程序分组
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);

// 按应用程序名称过滤
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 访问。

查询错误

如果你遇到查询错误:

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;"]
}

常见问题:

• 时间段格式不正确 (应该是在数组中的单个字符串 "start/end")
• 查询语句被拆分为单独的数组元素，而不是组合在一个字符串中

最常见的格式问题

最常见的错误是 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"]，query 为 ["statement1; statement2; RETURN = result;"]。 重要提示: 确保所有查询语句都在数组中的单个字符串中，而不是拆分为单独的数组元素。"

贡献

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

许可证

MIT