ActivityWatch MCP 服务器
一个模型上下文协议（MCP）服务器，使大型语言模型（LLM）代理能够进行查询和分析 ActivityWatch（可译为“活动监视器”或根据具体语境译为其他更贴切的名称） 时间追踪数据。
特点/功能
- 智能时间周期处理自然语言时间段，如“今天”、“本周”、“过去7天”
- 自动桶发现自动查找相关数据源
- 预聚合数据默认返回人类可读的摘要
- 内置过滤功能去除噪音（系统应用、本地主机、短时事件）
- 多设备支持跨多个设备汇总数据
- 全面分析窗口活动、网页浏览和周期总结
- 品类管理大语言模型辅助的类别创建、更新和组织
- ActivityWatch 集成对ActivityWatch的类别具有完全读/写访问权限
- 健康检查自动启动诊断和功能检测
- 全面日志记录可配置的日志记录，用于调试和监控
- 已准备好投入生产错误处理、优雅降级和操作可见性
代码库概览
总体架构
- 这个项目是一个MCP（模型上下文协议）服务器，它使LLM（大型语言模型）代理能够分析ActivityWatch数据。同时，它支持stdio（标准输入输出）接口
src/index.ts) 和 HTTP/SSE (src/http-server.ts) 入口点构建相同的MCP服务器实例，因此传输具有相同的行为。 - 运行时逻辑是分层的：传输层依赖于实现业务规则的服务类，而这些服务类又使用专用的ActivityWatch API客户端以及共享的实用工具。
重要组件
src/client/ActivityWatchClient(ActivityWatchClient) 标准化对ActivityWatch REST API（桶、事件、查询、设置）的访问，并集中处理错误，以便轻松模拟或扩展。- 这个（或：该）
src/services/该目录包含了能力检测、规范查询、统一活动聚合、分类管理、摘要生成以及日历集成等核心业务逻辑。在创建MCP服务器实例时，这些服务会被组合在一起，因此每个传输层都提供了相同的工具。 - 工具模式、格式化辅助工具和实用程序确保了对大型语言模型（LLM）友好的默认设置、规范过滤以及多种呈现格式。
开发工作流、命令和测试
- 日常开发通常使用HTTP传输方式通过
npm run start:http用于快速重启。支持文档涵盖IDE配置、环境变量以及连接故障排除。 - 测试使用Vitest，其中单元测试、集成测试和端到端测试套件均组织在（其下）
tests/，其中包含辅助文件夹和固定装置文件夹以避免重复。测试README文件说明了每一层所涵盖的内容以及如何运行它们。
新来者的建议后续步骤
- 按照快速入门指南来构建项目，配置Claude（或其他MCP客户端），并尝试使用发现工具来确认环境能够端到端正常工作。
- 研究架构和概念文档（规范事件、类别、工具参考），以了解统一活动数据是如何生成的，以及在扩展或调试工具时规范过滤为何重要。
- 通过将源文件与其对应的规范文件配对，探索各个服务和测试
tests/在做出更改或添加新工具之前，先明确预期的行为。 - 审查操作文档（日志记录、健康检查、HTTP服务器指南），以学习如何监控服务器、调整日志级别以及在开发或部署期间暴露MCP端点。
先决条件
- ActivityWatch（活动监控/活动追踪工具） 已安装并运行
- Node.js 18及以上版本
- ActivityWatch 服务器正在运行于
http://localhost:5600（默认）
安装
# Clone the repository
git clone https://github.com/auriora/activitywatch-mcp.git
cd activitywatch-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test测试
该项目包含一个使用Vitest的全面测试套件：
# Run all tests
npm test
# Run unit tests only
npm run test:unit
# Run integration tests only
npm run test:integration
# Run E2E tests only (requires ActivityWatch running)
npm run test:e2e
# Run tests in watch mode
npm run test:watch
# Run tests with coverage report
npm run test:coverage
# Run tests with UI
npm run test:ui测试结构：
tests/unit/- 实用程序和单个函数的单元测试tests/integration/- 服务交互的集成测试tests/e2e/- 对完整工作流进行端到端测试（需要ActivityWatch）tests/helpers/- 测试工具和模拟实现tests/fixtures/- 测试数据和模拟响应
见 tests/README.md（文件名，可翻译为“测试/README.md”） 以获取详细的测试文档。
配置
Docker
容器工件存放在 docker/直接构建并运行镜像：
docker build -f docker/Dockerfile -t activitywatch-mcp .
docker run --rm -p 3000:3000 activitywatch-mcp httpdocker-compose.yml 提供了一个与……连接的HTTP/SSE（服务器发送事件）栈 http://localhost:3000/mcp：
docker compose up通过复制来自定义默认设置 .env.example to .env 在运行 compose 之前。
通过以下方式将开发镜像发布到 GitHub Container Registry：
./scripts/docker-publish.sh通过 --build-only 跳过推送或 --push-only 重用现有的图像标签。
通过使用以下命令调用容器来切换到stdio模式： stdio 命令：
docker run --rm -it activitywatch-mcp stdio见 用于环境变量、配置文件和故障排除技巧。
许可证
此项目根据以下条款获得授权： GNU通用公共许可证第3版。
开发模式（HTTP服务器）
为了更快的开发速度，无需重启您的集成开发环境（IDE）：
npm run start:http然后配置Claude Desktop以使用HTTP传输：
{
"mcpServers": {
"activitywatch": {
"url": "http://localhost:3000/mcp"
}
}
}好处：
- ✅ 仅重启MCP服务器，不要重启你的IDE
- ✅ 快速的开发迭代
- ✅ 使用HTTP工具轻松调试
- ✅ 健康检查端点位于
http://localhost:3000/health
见 docs/developer/http-server-development.md 翻译为中文是：docs/开发者/HTTP服务器开发.md 完整的HTTP/SSE指南，包括辅助脚本、管理端点以及并发注意事项。
生产模式（stdio）
用于Claude桌面版的生产环境：
macOS（发音为“麦奥斯”）: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"activitywatch": {
"command": "node",
"args": ["/absolute/path/to/activitywatch-mcp/dist/index.js"]
}
}
}配置选项
你可以通过环境变量来定制服务器的行为：
{
"mcpServers": {
"activitywatch": {
"command": "node",
"args": ["/absolute/path/to/activitywatch-mcp/dist/index.js"],
"env": {
"AW_URL": "http://localhost:5600",
"LOG_LEVEL": "INFO"
}
}
}
}环境变量:
AW_URLActivityWatch 服务器 URL（默认：http://localhost:5600)LOG_LEVEL日志详细程度 -DEBUG，INFO，WARN或者ERROR（默认：INFO)
在以下情况下使用：
- 你需要根据特定的应用程序、域名或标题来过滤事件
- 您想结合多个过滤条件
- 标准工具无法提供所需的精确过滤功能
参数：
query_type，start_time，end_time- 过滤：
filter_afk，filter_apps，exclude_apps，filter_domains，filter_titles - 聚合：
merge_events，min_duration_seconds - 定制：
custom_query，bucket_ids - 输出：
limit，response_format
示例：
User: "Show me all my GitHub activity today"
LLM calls: aw_query_events({
query_type: "browser",
start_time: "2025-01-14T00:00:00Z",
end_time: "2025-01-14T23:59:59Z",
filter_domains: ["github.com"]
})______________________________________________________________________
9. aw_get_raw_events
从特定存储桶中检索原始事件。
仅在以下情况下使用：
- 你需要带有时间戳的精确事件数据
- 其他高级工具无法回答该查询
- 你正在调试或导出数据
参数：
bucket_id桶标识符（使用 aw_get_capabilities 发现）start_timeISO 8601 格式end_timeISO 8601 格式limit要返回的最大事件数（默认：100，最大：10000）response_format“简洁”|“详细”|“原始”
示例：
User: "Show me raw window events from 2pm to 3pm today"
LLM calls: aw_get_raw_events({
bucket_id: "aw-watcher-window_hostname",
start_time: "2025-01-14T14:00:00Z",
end_time: "2025-01-14T15:00:00Z"
})______________________________________________________________________
10. aw_list_categories
列出ActivityWatch中所有已配置的类别。
返回：
- 包含ID、名称和正则表达式模式的类别数组
- 总类别数
示例：
User: "What categories do I have configured?"
LLM calls: aw_list_categories()______________________________________________________________________
11. aw_add_category
为活动分类创建一个新的类别。
参数：
name用于层次名称的字符串数组（例如，\["工作", "电子邮件"\]）regex用于匹配活动的正则表达式模式
示例：
User: "Create a category for my gaming activities"
LLM calls: aw_add_category({
name: ["Entertainment", "Gaming"],
regex: "steam|epic|gog|game"
})______________________________________________________________________
12. aw_update_category
更新现有类别的名称或正则表达式模式。
参数：
id要更新的类别IDname（可选）新的层级名称regex（可选）新的正则表达式模式
示例：
User: "Add Thunderbird to my email category"
LLM calls: aw_update_category({
id: 1,
regex: "gmail|outlook|mail|thunderbird"
})______________________________________________________________________
13. aw_delete_category
从ActivityWatch中删除一个类别。
参数：
id要删除的类别ID
示例：
User: "Remove the gaming category"
LLM calls: aw_delete_category({ id: 5 })⚠️ 警告这将永久地从ActivityWatch中移除该类别。
______________________________________________________________________
建筑学
该服务器通过在代码中处理复杂逻辑，旨在最小化大型语言模型（LLM）的认知负荷：
- 时间段解析将自然语言中的时间段转换为精确的时间戳
- 桶发现（或桶探测）自动查找相关数据源
- 数据聚合预处理并汇总原始事件
- 过滤去除噪声（系统应用、本地主机、短暂事件）
- 规范化处理应用程序名称的变体和域名规范化
- 智能默认设置针对常见使用场景的合理参数默认值
发展
# Watch mode (auto-rebuild on changes)
npm run watch
# Build
npm run build
# Run directly
npm start故障排除
“未找到窗口活动桶”
原因ActivityWatch 窗口监视器未运行或未收集到任何数据。
解决方案:
- 确保ActivityWatch正在运行
- 检查一下
aw-watcher-window已安装并处于活动状态 - 使用
aw_get_capabilities查看可用的数据源有哪些
“无法连接到ActivityWatch”
原因ActivityWatch 服务器未运行或位于不同的 URL 上。
解决方案：
- 启动ActivityWatch
- 验证它正在运行于
http://localhost:5600 - 如果使用不同的URL，请设置
AW_URL环境变量
“日期格式无效”
原因日期字符串格式不正确。
解决方案使用“YYYY-MM-DD”格式（例如，“2025-01-14”）或ISO 8601格式。
日志记录和调试
该服务器包含全面的日志记录功能，用于故障排除和监控。
查看日志
日志被写入标准错误输出，并可在以下位置查看：
- Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”，但通常保留原名以体现品牌特色）在Claude的开发者控制台中检查MCP服务器日志
- 命令行直接运行服务器以在终端查看日志
日志级别
设置 LOG_LEVEL 环境变量用于控制详细程度：
DEBUG非常冗长 - 显示所有API调用、事件计数、时间范围INFO（默认）：信息性消息 - 工具调用、桶计数、结果WARN仅警告 - 缺失功能，失败的桶（或“失败的分组”）ERROR仅错误 - 连接失败，API错误
调试会话示例
{
"mcpServers": {
"activitywatch": {
"command": "node",
"args": ["/path/to/activitywatch-mcp/dist/index.js"],
"env": {
"LOG_LEVEL": "DEBUG"
}
}
}
}健康检查
服务器在启动时会进行自动健康检查：
- 验证ActivityWatch是否可达
- 检查服务器版本
- 统计可用的桶数量
- 检测追踪功能（窗口/浏览器/用户离开键盘）
- 记录缺少功能的警告日志
启动后检查日志以查看健康检查结果。
文档
- 文档中心： docs/index.md 翻译为中文是：“文档/索引文件（Markdown格式）” 以便进行全面导航。
- 计划： 文档/计划/ 对于具有前瞻性的举措。
- 更新： 文档/更新/ 对于已完成的实施日志。
- 贡献指南： \
CONTRIBUTING.md\翻译为中文是：“贡献指南/贡献说明文件”。这个文件通常用于说明如何向某个项目或组织做出贡献，包括贡献的流程、规范、期望等 - 行为准则： 《行为准则》.md
- 安全政策： \
SECURITY.md\翻译为中文是“安全说明文件”或“安全指南文件”
做出贡献
欢迎投稿！请从以下开始 \CONTRIBUTING.md\ 翻译为中文是：“贡献指南文件”或“贡献说明文件”。这个文件通常用于说明如何为项目做出贡献，包括代码贡献、文档编写、问题报告等方面的指南，并进行审查 docs/developer/http-server-development.md 翻译为中文是：“文档/开发者/HTTP服务器开发.md” 以及随附的测试指南 tests/README.md（文件名，可译为“tests/读我文件.md”或保持原样，因为文件名通常不翻译） 在提交拉取请求（PR）之前。
许可证
在……下分发 GNU通用公共许可证第3版。