ActivityWatch MCP Server

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

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

Installation

You can install the ActivityWatch MCP server either from npm or by building it yourself.

Installing from npm (coming soon)

# Global installation
npm install -g activitywatch-mcp-server

# Or install locally
npm install activitywatch-mcp-server

Building from Source

Clone this repository:
git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git cd activitywatch-mcp-server
Install dependencies:
npm install
Build the project:
npm run build

Prerequisites

ActivityWatch installed and running
Node.js (v14 or higher)
Claude for Desktop (or any other MCP client)

Usage

Using with Claude for Desktop

Open your Claude for Desktop configuration file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Add the MCP server configuration:

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

If you built from source, use:

{
  "mcpServers": {
    "activitywatch": {
      "command": "node",
      "args": ["/path/to/activitywatch-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude for Desktop
Look for the MCP icon in Claude's interface to confirm it's working

Example Queries

Here are some example queries you can try in Claude:

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?"

Available Tools

list-buckets

Lists all available ActivityWatch buckets with optional type filtering.

Parameters:

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

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_UNI-qUxy6XHnLkk'); 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

get-events

Get raw events from an ActivityWatch bucket.

Parameters:

bucketId: 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

get-settings

Get ActivityWatch settings from the server.

Parameters:

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

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

The server connects to the ActivityWatch API at http://localhost:5600 by default. If your ActivityWatch instance is running on a different host or port, you can modify this in the source code.

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

Claude/MCP Query Formatting Issues

If Claude reports errors when running queries through this MCP server, it's likely due to formatting issues. Make sure your query follows this exact format in your prompts:

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

Common issues:

Time periods not formatted correctly (should be "start/end" in a single string within an array)
Query statements split into separate array elements instead of being combined in one string

The Most Common Formatting Issue

The most frequent error is when Claude splits each query statement into its own array element like this:

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

This is INCORRECT. Instead, all statements should be in a single string within the array:

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

When Prompting Claude

When prompting Claude, be very explicit about the format and use examples. For instance, say:

"Run a query with timeperiods as ["2024-10-28/2024-10-29"] and query as ["statement1; statement2; RETURN = result;"]. Important: Make sure ALL query statements are in a single string within the array, not split into separate array elements."

Contributing

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

License

MIT

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

An interface that allows large language models like Claude to interact with ActivityWatch time tracking data through the Model Context Protocol, enabling queries about application usage, browsing history, and productivity patterns.

Related Resources

Reddit Discussion about this server

Related MCP Servers

Todoist Python MCP Server
Johnxjp
-
security
A
license
-
quality
A Model Context Profile server that enables Claude to interact with Todoist, allowing users to create, retrieve, update, and manage tasks through natural language commands.
Last updated -
1
Python
MIT License
ClickUp MCP Integration
Leanware-io
-
security
A
license
-
quality
A Model Context Protocol server that enables Large Language Models to interact with ClickUp workspace tasks and data, allowing creation and retrieval of tasks through natural language.
Last updated -
59
TypeScript
MIT License
Microsoft Todo MCP Service
jhirono
A
security
F
license
A
quality
A Model Context Protocol service for Claude that enables natural language interaction with Microsoft Todo tasks, including viewing task lists, creating tasks, and managing checklist items.
Last updated -
13
111
3
TypeScript
MCP Todoist
dkeesey
-
security
F
license
-
quality
A Model Context Protocol server that enables Claude to interact with your Todoist account, allowing you to manage tasks, projects, and labels through natural language.
Last updated -
1
Python

View all related MCP servers

ActivityWatch MCP Server