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

当催促克劳德时

提示克劳德时，要明确格式，并举例说明。例如，你可以说：

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

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

麻省理工学院

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

该接口允许大型语言模型（如 Claude）通过模型上下文协议与 ActivityWatch 时间跟踪数据进行交互，从而实现有关应用程序使用情况、浏览历史记录和生产力模式的查询。

Related Resources

Reddit Discussion about this server

Related MCP Servers

Todoist Python MCP Server
Johnxjp
-
security
A
license
-
quality
A Model Context Profile server that enables Claude to interact with Todoist, allowing users to create, retrieve, update, and manage tasks through natural language commands.
Last updated -
1
Python
MIT License
ClickUp MCP Integration
Leanware-io
-
security
A
license
-
quality
A Model Context Protocol server that enables Large Language Models to interact with ClickUp workspace tasks and data, allowing creation and retrieval of tasks through natural language.
Last updated -
59
TypeScript
MIT License
Microsoft Todo MCP Service
jhirono
A
security
F
license
A
quality
A Model Context Protocol service for Claude that enables natural language interaction with Microsoft Todo tasks, including viewing task lists, creating tasks, and managing checklist items.
Last updated -
13
111
3
TypeScript
MCP Todoist
dkeesey
-
security
F
license
-
quality
A Model Context Protocol server that enables Claude to interact with your Todoist account, allowing you to manage tasks, projects, and labels through natural language.
Last updated -
1
Python

View all related MCP servers

ActivityWatch MCP Server