ActivityWatch MCP Server

A Model Context Protocol (MCP) server that enables LLM agents to query and analyze ActivityWatch time tracking data.

Features

• Smart Time Period Handling: Natural language time periods like "today", "this_week", "last_7_days"

• Automatic Bucket Discovery: Finds relevant data sources automatically

• Pre-Aggregated Data: Returns human-readable summaries by default

• Built-in Filtering: Removes noise (system apps, localhost, short events)

• Multi-Device Support: Aggregates data across multiple devices

• Comprehensive Analysis: Window activity, web browsing, and period summaries

• Category Management: LLM-assisted category creation, updates, and organization

• ActivityWatch Integration: Full read/write access to ActivityWatch categories

• Health Checks: Automatic startup diagnostics and capability detection

• Comprehensive Logging: Configurable logging for debugging and monitoring

• Production Ready: Error handling, graceful degradation, and operational visibility

Codebase Overview

General Architecture

• The project is an MCP (Model Context Protocol) server that enables LLM agents to analyze ActivityWatch data. Both the stdio (src/index.ts) and HTTP/SSE (src/http-server.ts) entry points construct the same MCP server instance so transports share the same behavior.

• Runtime logic is layered: transports depend on service classes that implement business rules, which in turn use the dedicated ActivityWatch API client plus shared utilities.

Important Components

• src/client/ActivityWatchClient (ActivityWatchClient) standardizes access to the ActivityWatch REST API (buckets, events, queries, settings) and centralizes error handling so it is easy to mock or extend.

• The src/services/ directory contains the core business logic for capability detection, canonical queries, unified activity aggregation, category management, summaries, and calendar integration. These services are composed when creating the MCP server instance so every transport exposes identical tools.

• Tool schemas, formatting helpers, and utilities ensure LLM-friendly defaults, canonical filtering, and multiple presentation formats.

Development Workflow, Commands, and Tests

• Day-to-day development typically uses the HTTP transport via npm run start:http for quick restarts. Supporting docs cover IDE configuration, environment variables, and troubleshooting connectivity.

• Testing uses Vitest with unit, integration, and end-to-end suites organized under tests/, with helper and fixture folders to avoid duplication. The test README explains what each layer covers and how to run them.

Suggested Next Steps for Newcomers

1. Follow the quick start guide to build the project, configure Claude (or another MCP client), and try the discovery tools to confirm the environment works end to end.

2. Study the architecture and concept docs (canonical events, categories, tool reference) to understand how unified activity data is derived and why canonical filtering matters when extending or debugging tools.

3. Explore individual services and tests by pairing source files with their corresponding specs in tests/ to clarify expected behavior before making changes or adding new tools.

4. Review operational docs (logging, health checks, HTTP server guide) to learn how to monitor the server, tweak log levels, and expose the MCP endpoint during development or deployment.

Prerequisites

• ActivityWatch installed and running

• Node.js 18+

• ActivityWatch server running on http://localhost:5600 (default)

Installation

Testing

The project includes a comprehensive test suite using Vitest:

Test Structure:

• tests/unit/ - Unit tests for utilities and individual functions

• tests/integration/ - Integration tests for service interactions

• tests/e2e/ - End-to-end tests for complete workflows (requires ActivityWatch)

• tests/helpers/ - Test utilities and mock implementations

• tests/fixtures/ - Test data and mock responses

See tests/README.md for detailed testing documentation.

Configuration

Docker

Container artifacts live in docker/. Build and run the image directly:

docker-compose.yml provides an HTTP/SSE stack wired to http://localhost:3000/mcp:

Customize defaults by copying .env.example to .env before running compose.

Publish a development image to GitHub Container Registry via:

Pass --build-only to skip the push or --push-only to reuse an existing image tag.

Switch to stdio mode by invoking the container with the stdio command:

See docs/developer/docker.md for environment variables, profiles, and troubleshooting tips.

License

This project is licensed under the terms of the GNU General Public License v3.0.

Development Mode (HTTP Server)

For faster development without restarting your IDE:

Then configure Claude Desktop to use HTTP transport:

Benefits:

• ✅ Restart only the MCP server, not your IDE

• ✅ Fast development iteration

• ✅ Easy debugging with HTTP tools

• ✅ Health check endpoint at http://localhost:3000/health

See docs/developer/http-server-development.md for the full HTTP/SSE guide, including helper scripts, admin endpoints, and concurrency notes.

Production Mode (stdio)

For production use with Claude Desktop:

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

Configuration Options

You can customize the server behavior with environment variables:

Environment Variables:

• AW_URL: ActivityWatch server URL (default: http://localhost:5600)

• LOG_LEVEL: Logging verbosity - DEBUG, INFO, WARN, or ERROR (default: INFO)

Use this when:

• You need to filter events by specific apps, domains, or titles

• You want to combine multiple filtering criteria

• Standard tools don't provide the exact filtering needed

Parameters:

• query_type, start_time, end_time

• Filtering: filter_afk, filter_apps, exclude_apps, filter_domains, filter_titles

• Aggregation: merge_events, min_duration_seconds

• Custom: custom_query, bucket_ids

• Output: limit, response_format

Examples:

9. aw_get_raw_events

Retrieve raw events from a specific bucket.

Use this only when:

• You need exact event data with timestamps

• Other high-level tools cannot answer the query

• You're debugging or exporting data

Parameters:

• bucket_id: Bucket identifier (use aw_get_capabilities to discover)

• start_time: ISO 8601 format

• end_time: ISO 8601 format

• limit: Max events to return (default: 100, max: 10000)

• response_format: "concise" | "detailed" | "raw"

Example:

10. aw_list_categories

List all configured categories in ActivityWatch.

Returns:

• Array of categories with IDs, names, and regex patterns

• Total category count

Example:

11. aw_add_category

Create a new category for activity classification.

Parameters:

• name: Array of strings for hierarchical name (e.g., ["Work", "Email"])

• regex: Regular expression pattern to match activities

Example:

12. aw_update_category

Update an existing category's name or regex pattern.

Parameters:

• id: Category ID to update

• name: (Optional) New hierarchical name

• regex: (Optional) New regex pattern

Example:

13. aw_delete_category

Delete a category from ActivityWatch.

Parameters:

• id: Category ID to delete

Example:

⚠️ Warning: This permanently removes the category from ActivityWatch.

Architecture

The server is designed to minimize LLM cognitive load by handling complex logic in code:

• Time Period Parsing: Converts natural language periods to exact timestamps

• Bucket Discovery: Automatically finds relevant data sources

• Data Aggregation: Pre-processes and summarizes raw events

• Filtering: Removes noise (system apps, localhost, short events)

• Normalization: Handles app name variations and domain normalization

• Smart Defaults: Sensible parameter defaults for common use cases

Development

Troubleshooting

"No window activity buckets found"

Cause: ActivityWatch window watcher is not running or no data has been collected.

Solution:

1. Ensure ActivityWatch is running

2. Check that aw-watcher-window is installed and active

3. Use aw_get_capabilities to see what data sources are available

"Failed to connect to ActivityWatch"

Cause: ActivityWatch server is not running or is on a different URL.

Solution:

1. Start ActivityWatch

2. Verify it's running on http://localhost:5600

3. If using a different URL, set the AW_URL environment variable

"Invalid date format"

Cause: Date string is not in the correct format.

Solution: Use YYYY-MM-DD format (e.g., "2025-01-14") or ISO 8601 format.

Logging and Debugging

The server includes comprehensive logging for troubleshooting and monitoring.

Viewing Logs

Logs are written to stderr and can be viewed in:

• Claude Desktop: Check the MCP server logs in Claude's developer console

• Command Line: Run the server directly to see logs in terminal

Log Levels

Set the LOG_LEVEL environment variable to control verbosity:

• DEBUG: Very verbose - shows all API calls, event counts, time ranges

• INFO (default): Informational messages - tool calls, bucket counts, results

• WARN: Warnings only - missing features, failed buckets

• ERROR: Errors only - connection failures, API errors

Example Debug Session

Health Check

The server performs an automatic health check on startup:

• Verifies ActivityWatch is reachable

• Checks server version

• Counts available buckets

• Detects tracking capabilities (window/browser/AFK)

• Logs warnings for missing features

Check the logs after starting to see the health check results.

Documentation

• Docs hub: docs/index.md for full navigation.

• Plans: docs/plans/ for forward-looking initiatives.

• Updates: docs/updates/ for completed implementation logs.

• Contribution guide: CONTRIBUTING.md

• Code of Conduct: CODE_OF_CONDUCT.md

• Security policy: SECURITY.md

Contributing

Contributions are welcome! Start with CONTRIBUTING.md, and review docs/developer/http-server-development.md alongside the testing guide in tests/README.md before submitting a PR.

License

Distributed under the GNU General Public License v3.0.