ActivityWatch MCP server

The ActivityWatch MCP server provides integration between ActivityWatch time tracking and language models like Claude, allowing access to your time tracking data through natural language queries.

Installation Options

Installing from npm (coming soon)

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

# Or install locally
npm install activitywatch-mcp-server

Building from Source

1. Clone the repository:

   git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
   cd activitywatch-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Prerequisites

Before using the ActivityWatch MCP server, ensure you have:

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

Setting Up with Claude for Desktop

1. Open your Claude for Desktop configuration file:

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

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

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

Using the Server

Example Queries

Try these natural language queries with Claude:

• "What ActivityWatch buckets do I have?"
• "Can you show me which applications I've used the most today?"
• "What websites have I spent the most time on today?"
• "How much time have I spent in productivity apps today?"
• "What are my ActivityWatch settings?"

Available Tools

list-buckets

Lists all available ActivityWatch buckets.

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 (e.g., ["2024-10-28/2024-10-29"])
• query: Array of query statements in AQL
• name (optional): Name for the query (used for caching)

Example request format:

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

get-events

Get raw events from a 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.

Parameters:

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

Query Language Examples

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

Troubleshooting

ActivityWatch Connection

Ensure ActivityWatch is running and accessible at http://localhost:5600.

Query Formatting Issues

When running queries through the MCP server, format must be exact:

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

Common mistakes:

• All query statements must be in a single string within the array, separated by semicolons
• Time periods should be formatted as "start/end" in a single string
• Bucket IDs must be correct

When prompting Claude, be explicit: "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."

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "activitywatch" '{"command":"activitywatch-mcp-server","args":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect