playbooks

home / mcp / activitywatch mcp server

ActivityWatch MCP Server

Model Context Protocol server for ActivityWatch time tracking data

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "8bitgentleman-activitywatch-mcp-server": {
      "command": "activitywatch-mcp-server",
      "args": []
    }
  }
}

The ActivityWatch MCP Server lets you connect ActivityWatch data with large language models and other MCP clients, enabling you to browse buckets, run AQL queries, fetch raw events, and view settings from your ActivityWatch instance through simple MCP calls.

How to use

You can interact with ActivityWatch data through an MCP client by querying buckets, running AQL statements, retrieving raw events, and inspecting settings. Use the MCP server as a bridge between ActivityWatch and your client experiences, such as chat prompts or automation workflows.

Typical usage patterns include listing available buckets to understand what data you have, executing targeted queries to retrieve time-based events, pulling specific event data from a bucket, and inspecting or validating your ActivityWatch configuration. You can combine these capabilities with your MCP client’s prompts to build insights about your daily activity, application usage, and web activity.

If you are using Claude for Desktop or another MCP client, configure the client to start the MCP server as shown in the installation steps. Once the client restarts, look for the MCP icon or the connected server indicator in the client UI to confirm the connection is active.

How to install

Prerequisites you need before installing the MCP server:

  • ActivityWatch installed and running
  • Node.js version 14 or higher
  • An MCP client such as Claude for Desktop or another MCP-compatible client

Option 1: Install from npm (global)

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

# Or install locally
npm install activitywatch-mcp-server

Option 2: Build from source

# Clone the 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

Configure and run with an MCP client

Choose one of the following runtime configurations for your MCP client to start the server.

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

If you built from source, point to the built entry file instead of a globally installed binary.

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

Example client configuration for Claude for Desktop

Add the MCP server to Claude for Desktop configuration under mcpServers. This is an example you can adapt to your environment.

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

Available tools

list-buckets

Lists all available ActivityWatch buckets with optional type filtering and the option to include bucket data in responses.

run-query

Executes a query against ActivityWatch using its query language (AQL), supporting time periods, statements, and optional query caching.

get-events

Retrieves raw events from a specified ActivityWatch bucket, with optional start, end, and limit controls.

get-settings

Fetches ActivityWatch settings from the server, with an option to query a specific key.