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

1. Clone this 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

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

Usage

Using 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 a rootless podman container on Linux with Gemini CLI

Make sure to build the image first with:

version=$(npm pkg get version | tr -d '"')
podman build . -t activitywatch-mcp-server:${version}

This example uses the override for Activity Watch not being available on 127.0.0.1 (see next section). If not required, you may omit the AW_API_BASE environment variable.

{
  "mcpServers": {
    "activitywatch-mcp-server": {
      "command": "/usr/bin/podman",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--userns=keep-id",
        "-e",
        "AW_API_BASE",
        "localhost/activitywatch-mcp-server:1.2.1"
      ],
      "env": {
        "AW_API_BASE": "http://mydesktop.local:5600/api/0"
      }
    }
  }
}

Override ActivityWatch server host/port

If you want to run this MCP server from inside Windows Subsystem for Linux, for instance within a container, the AW server running in Windows will not be available at 127.0.0.1. To override the standard localhost connection, use the environment variable AW_API_BASE or the --aw-api-base flag, as below:

# Using environment variable
export AW_API_BASE=http://mydesktop.local:5600/api/0
node dist/index.js

# Or using command-line flag
node dist/index.js --aw-api-base=http://mydesktop.local:5600/api/0

NOTE: The AW server may be fussy about the name used to connect to it, but it will accept a name that matches the computer name where it is running with a .local suffix.

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 o

... View full README on GitHub