Activitywatch MCP Server Py

活动监视MCP服务器

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

版本2.0：现在用Python实现，支持原生UVX！该服务器最初内置于TypeScript中，现已完全用Python重写，以便更好地与Python生态系统集成，并通过以下方式简化部署 uvx.

特性

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

安装

使用紫外线（推荐）

使用时 uv 不需要特定的安装。我们将使用 uvx 直接运行 _activitywatch mcp服务器py_.

uvx activitywatch-mcp-server-py

使用pip

或者，您可以安装 activitywatch-mcp-server-py 通过pip：

pip install activitywatch-mcp-server-py

安装后，您可以使用以下命令将其作为脚本运行：

python -m activitywatch_mcp_server_py

先决条件

• 活动观察 已安装并正在运行
• Python 3.10或更高版本（由uvx自动处理）
• MCP客户端（Claude Desktop、OpenCode、Crush等）

配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

Using uvx (recommended)

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

Using pip installation

{
    "mcpServers": {
        "activitywatch": {
            "command": "python",
            "args": ["-m", "activitywatch_mcp_server_py"]
        }
    }
}

With custom API endpoint

{
    "mcpServers": {
        "activitywatch": {
            "command": "uvx",
            "args": [
                "activitywatch-mcp-server-py",
                "--api-base",
                "http://localhost:5600/api/0"
            ],
            "env": {
                "AW_API_BASE": "http://localhost:5600/api/0"
            }
        }
    }
}

配置后，重新启动Claude Desktop并查找MCP图标以确认其正常工作。

开源代码

OpenCode支持开箱即用的MCP服务器。将服务器配置添加到您的OpenCode设置中：

Using uvx

{
    "mcp": {
        "servers": {
            "activitywatch": {
                "command": "uvx",
                "args": ["activitywatch-mcp-server-py"]
            }
        }
    }
}

Using pip installation

{
    "mcp": {
        "servers": {
            "activitywatch": {
                "command": "python",
                "args": ["-m", "activitywatch_mcp_server_py"]
            }
        }
    }
}

您可以将此添加到：

• 用户设置（JSON）：新闻 Ctrl+Shift+P 然后选择“首选项：打开用户设置（JSON）”
• 工作区设置：创建 .vscode/mcp.json 在您的工作空间中

心动

Crush还支持MCP服务器。在您的粉碎设置中配置它：

Using uvx

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

Using pip installation

{
    "mcpServers": {
        "activitywatch": {
            "command": "python",
            "args": ["-m", "activitywatch_mcp_server_py"]
        }
    }
}

可用工具

活动观察列表桶

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

参数：

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

activitywatch运行查询

使用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_hostname'); RETURN = events;"
    ]
}

请注意：

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

activitywatch获取事件

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

参数：

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

activitywatch获取设置

从服务器获取ActivityWatch设置。

参数：

• key （可选）：获取特定设置键，而不是所有设置

activitywatch查询示例

获取ActivityWatch MCP服务器格式正确的查询示例。此工具不接受任何参数，并返回有用的示例。

查询示例

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

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

查询语言示例

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/api/0 默认情况下。

您可以使用以下方式对此进行自定义：

1. 命令行参数：

   uvx activitywatch-mcp-server-py --api-base http://localhost:5600/api/0

1. 环境变量：

   export AW_API_BASE=http://localhost:5600/api/0
   uvx activitywatch-mcp-server-py

故障排除

活动观察未运行

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

查询错误

如果您遇到查询错误：

1. 检查查询语法
2. 确保存储桶ID正确
3. 验证时间段是否包含数据
4. 查看ActivityWatch日志以了解更多详细信息
5. 使用 activitywatch-query-examples 查看格式正确的示例的工具

查询格式问题

最常见的错误是查询语句被拆分为单独的数组元素，而不是组合在一个字符串中：

❌ 不正确：

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

结构

类别模型

flowchart LR
  subgraph "MCP Server"
    direction TB
    classDef server fill:#e1f5fe
    classDef tool fill:#f3e5f6
    classDef handler fill:#fff3e0

    A[server.py] --> B[tools/]
    A --> C[server.py]

    class A server
    class B tool
    class C handler
  end

  subgraph "ActivityWatch API"
    direction TB
    classDef api fill:#e8f5e8

    D[localhost:5600]

    class D api
  end

  subgraph "MCP Client"
    direction TB
    classDef client fill:#fce4ec

    E[Claude Desktop]
    F[OpenCode]

    class E client
    class F client
  end

  A --> D
  E --> A
  F --> A

项目结构

activitywatch mcp服务器/ ├── src/ │ └── activitywatch_mcp_server_py/ │ ├── 初始化.py#入口点和CLI │ ├── server.py#MCP服务器设置 │ └── 工具/#单个工具实现 │ ├── list_buckets.py │ ├── run_query.py │ ├── get_events.py │ ├── get_settings.py │ └── query_example.py ├── 测试/#测试套件 │ ├── conftest.py │ ├── test_list_buckets.py │ ├── test_run_query.py │ └── test_get_settings.py ├── pyproject.toml#项目配置 └── README.md

### Setup Development Environment

Clone the repository

git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git cd activitywatch-mcp-server

Create virtual environment and install dependencies

python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

Install in editable mode with dev dependencies

uv pip install -e ".[dev]"

### 运行测试

Run all tests

pytest tests/ -v

Run specific test file

pytest tests/test_list_buckets.py -v

Run with coverage

pytest tests/ --cov=src/activitywatch_mcp_server_py --cov-report=html

Run type checking

pyright src/

Run linting

ruff check src/

### 在本地测试服务器

Run the server directly

source .venv/bin/activate activitywatch-mcp-server-py

Test with custom API endpoint

activitywatch-mcp-server-py --api-base http://localhost:5600/api/0

Test with environment variable

AW_API_BASE=http://localhost:5600/api/0 activitywatch-mcp-server-py

### 调试

您可以使用MCP检查器调试服务器：

npx @modelcontextprotocol/inspector uvx activitywatch-mcp-server-py

这将打开一个web界面，您可以在其中：

- 查看所有可用工具
- 具有自定义参数的测试工具调用
- 查看请求/响应数据
- 调试服务器通信

### 添加新工具

要添加新工具，请执行以下操作：

1. 在中创建新文件 `src/activitywatch_mcp_server_py/tools/` （例如。， `my_tool.py`)

1. 实现模式函数和处理程序：

from mcp.types import TextContent from typing import Any

def my_tool_schema() -> dict[str, Any]: return { "type": "object", "properties": { "param": {"type": "string", "description": "Parameter description"} }, "required": ["param"] }

async def my_tool_handler(api_base: str, arguments: dict[str, Any]) -> list[TextContent]: # Implementation here return [TextContent(type="text", text="Result")]

1. 在中注册该工具 `server.py`:

from activitywatch_mcp_server_py.tools.my_tool import my_tool_schema, my_tool_handler

# In list_tools handler: Tool( name="activitywatch-my-tool", description="Tool description", inputSchema=my_tool_schema(), ),

# In call_tool handler: case "activitywatch-my-tool": return await my_tool_handler(api_base, arguments)

1. 在中编写测试 `tests/test_my_tool.py`

### 发布过程

该软件包旨在发布到PyPI，以便通过以下方式轻松安装 `uvx`:

Update version in pyproject.toml

Build the package

python -m build

Upload to PyPI (requires PyPI credentials)

twine upload dist/*

Test installation

uvx activitywatch-mcp-server-py

## 贡献

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

## 许可证

[麻省理工学院](LICENSE)