项目简介

'ActivityWatch MCP 服务器 (Swift)' 是一个用 Swift 语言实现的 Model Context Protocol (MCP) 服务器。它旨在连接到你的本地 ActivityWatch 应用，将你的时间追踪数据以标准化的方式暴露给兼容 MCP 协议的 AI 客户端（如 Claude Desktop）。通过这个服务器，AI 助手可以轻松查询你的活动数据、分析工作效率、提取关键信息，并支持自然语言日期查询，让数据交互更加直观和智能。

主要功能点

获取数据源列表: 允许你查看所有可用的 ActivityWatch 数据桶（buckets），并可根据类型（如“窗口”、“离开状态”）进行筛选。
查询活跃数据源: 帮助你找出在特定时间范围内有活动的数据桶，快速了解数据概览。
提取活跃文件夹: 从应用窗口标题中识别并提取独特的文件夹路径，帮你了解在哪些项目或目录下花费了时间。
获取文件夹活动详情: 深入分析特定时间段内本地文件夹的活动，包括停留时间、事件数量、按应用分组等，并支持从终端标题中提取项目上下文信息。
运行自定义查询: 直接执行强大的 ActivityWatch Query Language (AQL) 查询，为你提供灵活的数据获取能力。
获取原始事件: 从指定数据桶中检索原始活动事件数据，支持详细的时间范围过滤。
访问 ActivityWatch 设置: 允许获取 ActivityWatch 的配置信息。
提供查询示例: 内置常用 AQL 查询模式示例，方便用户参考和学习。
引导式效率分析: 提供用于生产力分析的引导式 Prompt 模板，帮助 AI 助手更好地理解和分析你的活动。
支持自然语言日期: 所有日期参数均支持“今天”、“昨天”、“上周”、“3天前”等自然语言描述，极大简化了查询操作。

安装步骤

前提条件:
- 确保你的 macOS 系统版本为 15.0 或更高。
- 已安装 Swift 6.0 或更高版本。
- 你的设备上已安装并正在本地运行 ActivityWatch。
- 已安装 Swift Package Manager (通常随 Swift 一起安装)。
快速安装 (推荐): 在终端中运行以下命令：
```
./install.sh
```

手动安装: 如果快速安装失败，可以按照以下步骤手动构建和安装：

# 构建项目，生成可执行文件
swift build -c release

# 将可执行文件安装到系统默认路径（通常是 ~/.swiftpm/bin/）
swift package experimental-install

服务器配置

为了让你的 MCP 客户端（如 Claude Desktop）能够连接到 ActivityWatch MCP 服务器，你需要将以下 JSON 格式的配置添加到客户端的配置文件中。

macOS 用户: 通常在 '~/Library/Application Support/Claude/claude_desktop_config.json' Linux 用户: 通常在 '~/.config/Claude/claude_desktop_config.json'

请将以下内容添加到你的 MCP 客户端配置文件的 'mcpServers' 部分：

{
  "mcpServers": {
    "activitywatch-mcp": {
      "command": "~/.swiftpm/bin/activitywatch-mcp",
      "args": ["--log-level", "info"]
    }
  }
}

配置说明:

'"activitywatch-mcp"'：这是你为 ActivityWatch MCP 服务器定义的唯一名称，客户端将通过此名称来引用它。
'"command"'：指定 MCP 服务器可执行文件的完整路径。如果使用手动安装，默认路径是 '~/.swiftpm/bin/activitywatch-mcp'。
'"args"'：传递给服务器的启动参数列表。
- '"--log-level [级别]"'：设置服务器的日志输出级别。可选值包括 'debug'（调试）、'info'（信息）、'warning'（警告）、'error'（错误）、'critical'（致命）。
- '"--server-url [URL]"'：如果 ActivityWatch 服务器没有运行在默认地址 'http://localhost:5600'，你可以通过此参数指定其自定义 URL。

基本使用方法

配置完成后，你的 MCP 客户端就能通过 AI 助手与 ActivityWatch MCP 服务器交互。以下是一些通过 AI 助手调用服务器功能的示例，你可以直接向 AI 助手提问或发出指令：

列出所有数据源: “使用 'list-buckets' 工具，查看所有可用的 ActivityWatch 数据源。” “帮我列出所有类型为 'window' 的数据桶。”
运行 AQL 查询: “使用 'run-query' 工具，查询从昨天开始到今天结束的所有窗口活动事件。” （注意：对于 AQL 查询，可能需要提供更详细的时间段和查询字符串）
获取今日活跃文件夹: “使用 'active-folders' 工具，查询我今天活跃过的所有文件夹。” “获取从 '3 days ago' 到 'now' 的活跃文件夹列表。”
获取过去一周的文件夹活动详情: “使用 'get-folder-activity' 工具，分析我过去一周在各个文件夹中的活动详情，包括每个文件夹花费的时间。” “请获取从 'last monday' 到 'today' 的文件夹活动报告，并包含网络活动。”
查询示例: “使用 'query-examples' 工具，给我一些常见的 ActivityWatch Query Language (AQL) 查询模式示例。”
获取特定时间段的原始事件: “使用 'get-events' 工具，从名为 'aw-watcher-window_yourhostname' 的数据桶中，获取从 '2024-01-01T00:00:00Z' 到 '2024-01-02T00:00:00Z' 的所有窗口活动事件，限制结果为100条。”

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息