# 上下文服务（MCP）
## 基本信息
- Slug: `8bitgentleman-activitywatch-mcp-server`
- Source: modelscope
- Publisher: @8bitgentleman/activitywatch-mcp-server
- Categories: monitoring / os-automation / knowledge-and-memory
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@8bitgentleman/activitywatch-mcp-server
## 简介
一个接口，允许像 Claude 这样的大型语言模型通过模型上下文协议与 ActivityWatch 时间跟踪数据交互，从而实现对应用程序使用情况、浏览历史和生产力模式的查询。
## 安装提示

```bash
# Global installation npm install -g activitywatch-mcp-server # Or install locally npm install activitywatch-mcp-server
```

## MCP Server 详情

# ActivityWatch MCP 服务器

一个连接到 [ActivityWatch](https://activitywatch.net/) 的 Model Context Protocol (MCP) 服务器，允许像 Claude 这样的大语言模型与您的时间跟踪数据进行交互。

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

## 功能

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

## 安装

您可以从 npm 或通过自行构建来安装 ActivityWatch MCP 服务器。

### 从 npm 安装（即将推出）

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

# Or install locally
npm install activitywatch-mcp-server
```


### 从源代码构建

1. 克隆此仓库：
   ```bash
   git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
   cd activitywatch-mcp-server
   ```

2. 安装依赖项：
   ```bash
   npm install
   ```

3. 构建项目：
   ```bash
   npm run build
   ```

## 前提条件

- 已安装并正在运行 [ActivityWatch](https://activitywatch.net/)
- 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 服务器配置：

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


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

```json
{
  "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`（可选）：查询的名称（用于缓存）

**重要**: 每个查询字符串应包含一个完整的查询，多个语句之间用分号分隔。

示例请求格式：
```json
{
  "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 正在运行并且可以通过 [http://localhost:5600](http://localhost:5600) 访问。

### 查询错误

如果您遇到查询错误：

1. 检查您的查询语法
2. 确保存储桶 ID 是正确的
3. 验证时间段内包含数据
4. 查看 ActivityWatch 日志以获取更多详细信息

### Claude/MCP 查询格式问题

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

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


常见问题：

- 时间段格式不正确（应在数组内的单个字符串中为 "开始/结束"）
- **查询语句被拆分成单独的数组元素而不是组合在一个字符串中**

#### 最常见的格式问题

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

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


这是不正确的。相反，所有语句应该在一个数组内的单个字符串中：

```json
{
  "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 时，请非常明确地说明格式并使用示例。例如，可以说：

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

## 贡献

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

## 许可证

[MIT](LICENSE)