使用说明

活动监视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 默认情况下。

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

命令行参数：

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

环境变量：

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

故障排除

活动观察未运行

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

查询错误

如果您遇到查询错误：

检查查询语法
确保存储桶ID正确
验证时间段是否包含数据
查看ActivityWatch日志以了解更多详细信息
使用 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

```bash
# 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界面，您可以在其中：

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

添加新工具

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

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

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

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")]

在中注册该工具 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)

在中编写测试 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

贡献

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

许可证

麻省理工学院

使用说明

活动监视MCP服务器

特性

安装

使用紫外线（推荐）

使用pip

先决条件

配置

克劳德桌面

开源代码

心动

可用工具

活动观察列表桶

activitywatch运行查询

activitywatch获取事件

activitywatch获取设置

activitywatch查询示例

查询示例

查询语言示例

配置选项

故障排除

活动观察未运行

查询错误

查询格式问题

结构

项目结构

运行测试

在本地测试服务器

调试

添加新工具

发布过程

贡献

许可证

相关 MCP

MySQL查询服务器

Qdrant向量搜索MCP服务器

知识图谱记忆系统

科学研究的开源MCP服务器

Prometheus MCP 服务器

Python解释器服务