ActivityWatch Narrator

Generate narrative summaries from ActivityWatch data using the Model Context Protocol (MCP).

Overview

ActivityWatch Narrator is an MCP server that exposes ActivityWatch activity tracking data to AI assistants like Claude. It allows you to query, analyze, and generate narrative summaries of your computer usage patterns.

Features

• MCP Server Integration - Connect your ActivityWatch data to Claude Desktop and other MCP clients
• Activity Querying - Fetch raw events and enriched activities from any time range
• Narrative Summaries - Generate human-readable summaries of your activities
• Bucket Management - List and query all ActivityWatch data buckets
• Time Range Analysis - Analyze activities across custom time periods

Quick Start

Prerequisites

1. ActivityWatch running on http://localhost:5600
2. Python 3.11 or later
3. pip or another Python package manager

Installation

Using uvx (Recommended)

Run directly without installation:

# From PyPI (once published)
uvx aw-narrator

# From local directory
uvx --from . aw-narrator

# From Git repository
uvx --from git+https://github.com/activitywatch/aw-narrator aw-narrator

Using pip

# Clone the repository
git clone https://github.com/activitywatch/aw-narrator.git
cd aw-narrator

# Install dependencies
pip install -e .

# Or using development dependencies
pip install -e ".[dev]"

Running the MCP Server

# Using uvx (if installed via pip or uvx)
aw-narrator-mcp

# Or using Python module
python -m aw_narrator.mcp

# Using uvx without installation
uvx --from . aw-narrator-mcp

# Server will start on http://127.0.0.1:8001

Verify it's running:

curl http://127.0.0.1:8001/health

Connecting to Claude Desktop

See MCP Setup Guide for detailed configuration instructions.

Quick config - Add to your Claude Desktop config file:

{
  "mcpServers": {
    "activitywatch-narrator": {
      "command": "python",
      "args": ["-m", "aw_narrator.mcp"],
      "cwd": "/path/to/activitywatch-narrator",
      "env": {
        "AW_MCP_ACTIVITYWATCH_URL": "http://localhost:5600"
      }
    }
  }
}

Available Tools

The MCP server provides these tools to AI assistants:

1. get_activitywatch_status - Check ActivityWatch server availability
2. list_activitywatch_buckets - List all available data buckets
3. get_bucket_events - Fetch events from a bucket within a time range
4. get_enriched_activities - Get processed activity data
5. generate_activity_summary - Create narrative summaries

Usage Examples

Once connected through Claude Desktop, you can ask:

• "What did I work on today?"
• "Show me my most used applications this week"
• "Generate a summary of my activities from 9am to 5pm yesterday"
• "What ActivityWatch buckets do I have available?"

Configuration

Configure via environment variables:

• AW_MCP_HOST - Server host (default: 127.0.0.1)
• AW_MCP_PORT - Server port (default: 8001)
• AW_MCP_ACTIVITYWATCH_URL - ActivityWatch URL (default: http://localhost:5600)

Example:

AW_MCP_PORT=8002 python -m aw_narrator.mcp

Development

Running Tests

# Run all tests
pytest

# With coverage
pytest --cov=aw_narrator

# Run specific test file
pytest tests/integration/test_activitywatch_integration.py

Code Quality

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

Project Structure

activitywatch-narrator/
├── src/aw_narrator/
│   ├── adapters/         # External service adapters (ActivityWatch)
│   ├── cli/              # Command-line interface
│   ├── core/             # Domain models and business logic
│   └── mcp/              # MCP server implementation
├── tests/
│   ├── integration/      # Integration tests
│   └── unit/             # Unit tests
├── docs/                 # Documentation
│   ├── MCP_SETUP.md     # MCP configuration guide
│   └── adr/             # Architecture decision records
└── pyproject.toml       # Project configuration

Documentation

• MCP Setup Guide - Complete MCP configuration instructions
• Architecture Decisions - ADRs and technical decisions
• Design Document - System architecture and design
• Project Plan - User stories and roadmap

Contributing

Contributions are welcome! Please:

1. Follow the existing code style (black, isort, ruff)
2. Add tests for new features
3. Update documentation as needed
4. Create an ADR for significant architectural changes

License

MIT License - see LICENSE file for details

Links

• ActivityWatch
• Model Context Protocol
• FastMCP

Support

• Issues: GitHub Issues
• ActivityWatch Forum: forum.activitywatch.net