ActivityWatch MCP Server

A Model Context Protocol (MCP) server that connects to ActivityWatch, allowing LLMs like Claude to interact with your time tracking data.

Version 2.0: Now implemented in Python with native UVX support! Originally built in TypeScript, this server has been completely rewritten in Python for better integration with the Python ecosystem and simplified deployment via uvx.

Features

List Buckets: View all available ActivityWatch buckets
Run Queries: Execute powerful AQL (ActivityWatch Query Language) queries
Get Raw Events: Retrieve events directly from any bucket
Get Settings: Access ActivityWatch configuration settings
Query Examples: Get helpful examples of properly formatted queries

Installation

Using UV (Recommended)

When using uv no specific installation is needed. We will use uvx to directly run activitywatch-mcp-server-py.

uvx activitywatch-mcp-server-py

Using pip

Alternatively you can install activitywatch-mcp-server-py via pip:

pip install activitywatch-mcp-server-py

After installation, you can run it as a script using:

python -m activitywatch_mcp_server_py

Prerequisites

ActivityWatch installed and running
Python 3.10 or higher (automatically handled by uvx)
An MCP client (Claude Desktop, OpenCode, Crush, etc.)

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %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"
            }
        }
    }
}

After configuration, restart Claude Desktop and look for the MCP icon to confirm it's working.

OpenCode

OpenCode supports MCP servers out of the box. Add the server configuration to your OpenCode settings:

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

You can add this to:

User Settings (JSON): Press Ctrl+Shift+P and select "Preferences: Open User Settings (JSON)"
Workspace Settings: Create .vscode/mcp.json in your workspace

Crush

Crush also supports MCP servers. Configure it in your Crush settings:

Using uvx

{
    "mcpServers": {
        "activitywatch": {
            "command": "uvx",
            "args": ["activitywatch-mcp-server-py"]
        }
    }
}

Using pip installation

{
    "mcpServers": {
        "activitywatch": {
            "command": "python",
            "args": ["-m", "activitywatch_mcp_server_py"]
        }
    }
}

Available Tools

activitywatch-list-buckets

Lists all available ActivityWatch buckets with optional type filtering.

Parameters:

type (optional): Filter buckets by type (e.g., "window", "web", "afk")
include_data (optional): Include bucket data in response

activitywatch-run-query

Run a query in ActivityWatch's query language (AQL).

Parameters:

timeperiods: Time period(s) to query formatted as array of strings. For date ranges, use format: ["2024-10-28/2024-10-29"]
query: Array of query statements in ActivityWatch Query Language, where each item is a complete query with statements separated by semicolons
name (optional): Name for the query (used for caching)

IMPORTANT: Each query string should contain a complete query with multiple statements separated by semicolons.

Example request format:

{
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": [
        "events = query_bucket('aw-watcher-window_hostname'); RETURN = events;"
    ]
}

Note that:

timeperiods should have pre-formatted date ranges with slashes
Each item in the query array is a complete query with all statements

activitywatch-get-events

Get raw events from an ActivityWatch bucket.

Parameters:

bucket_id: ID of the bucket to fetch events from
start (optional): Start date/time in ISO format
end (optional): End date/time in ISO format
limit (optional): Maximum number of events to return

activitywatch-get-settings

Get ActivityWatch settings from the server.

Parameters:

key (optional): Get a specific settings key instead of all settings

activitywatch-query-examples

Get examples of properly formatted queries for the ActivityWatch MCP server. This tool takes no parameters and returns helpful examples.

Example Queries

Here are some example queries you can try:

List all your buckets: "What ActivityWatch buckets do I have?"
Get application usage summary: "Can you show me which applications I've used the most today?"
View browsing history: "What websites have I spent the most time on today?"
Check productivity: "How much time have I spent in productivity apps today?"
View settings: "What are my ActivityWatch settings?" or "Can you check a specific setting in ActivityWatch?"

Query Language Examples

ActivityWatch uses a simple query language. Here are some common patterns:

// 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;

Configuration Options

The server connects to the ActivityWatch API at http://localhost:5600/api/0 by default.

You can customize this using:

Command-line argument:

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

Environment variable:

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

Troubleshooting

ActivityWatch Not Running

If ActivityWatch isn't running, the server will show connection errors. Make sure ActivityWatch is running and accessible at http://localhost:5600.

Query Errors

If you're encountering query errors:

Check your query syntax
Make sure the bucket IDs are correct
Verify that the timeperiods contain data
Check ActivityWatch logs for more details
Use the activitywatch-query-examples tool to see properly formatted examples

Query Formatting Issues

The most frequent error is when query statements are split into separate array elements instead of being combined in one string:

❌ INCORRECT:

{
    "query": [
        "browser_events = query_bucket('aw-watcher-web');",
        "afk_events = query_bucket('aw-watcher-afk');",
        "RETURN = events;"
    ],
    "timeperiods": ["2024-10-28/2024-10-29"]
}

✅ CORRECT:

{
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": [
        "browser_events = query_bucket('aw-watcher-web'); afk_events = query_bucket('aw-watcher-afk'); RETURN = events;"
    ]
}

Structure

Class Model

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

Project Structure

activitywatch-mcp-server/ ├── src/ │ └── activitywatch_mcp_server_py/ │ ├── init.py # Entry point and CLI │ ├── server.py # MCP server setup │ └── tools/ # Individual tool implementations │ ├── list_buckets.py │ ├── run_query.py │ ├── get_events.py │ ├── get_settings.py │ └── query_examples.py ├── tests/ # Test suite │ ├── conftest.py │ ├── test_list_buckets.py │ ├── test_run_query.py │ └── test_get_settings.py ├── pyproject.toml # Project configuration └── 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]"

Running Tests

# 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/

Testing the Server Locally

# 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

Debugging

You can use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector uvx activitywatch-mcp-server-py

This will open a web interface where you can:

See all available tools
Test tool calls with custom parameters
View request/response data
Debug server communication

Adding New Tools

To add a new tool:

Create a new file in src/activitywatch_mcp_server_py/tools/ (e.g., my_tool.py)

Implement the schema function and handler:

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

Register the tool in 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)

Write tests in tests/test_my_tool.py

Release Process

The package is designed to be published to PyPI for easy installation via 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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.github/workflows		.github/workflows
Docs		Docs
build/lib/mcp_server_activitywatch		build/lib/mcp_server_activitywatch
src		src
tests		tests
.DS_Store		.DS_Store
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
HANDOFF.md		HANDOFF.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
SESSION_SUMMARY.md		SESSION_SUMMARY.md
Taskfile.yaml		Taskfile.yaml
codeowners		codeowners
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

ActivityWatch MCP Server

Features

Installation

Using UV (Recommended)

Using pip

Prerequisites

Configuration

Claude Desktop

OpenCode

Crush

Available Tools

activitywatch-list-buckets

activitywatch-run-query

activitywatch-get-events

activitywatch-get-settings

activitywatch-query-examples

Example Queries

Query Language Examples

Configuration Options

Troubleshooting

ActivityWatch Not Running

Query Errors

Query Formatting Issues

Structure

Project Structure

Running Tests

Testing the Server Locally

Debugging

Adding New Tools

Release Process

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages