activitywatch

The ActivityWatch MCP Server exposes a small API that allows large language models (like Claude) to query and interact with your ActivityWatch data. It supports core actions such as listing available buckets, running AQL queries against ActivityWatch, fetching raw events from a bucket, and retrieving current ActivityWatch settings. You can connect to this MCP server from Claude or any other MCP client by configuring the client to point at the server, using either an installed binary via npm/npx or a locally built Node.js version depending on how you run it. Typical interactions include listing buckets to discover data sources, executing AQL queries to aggregate application usage or time-tracking data, pulling raw events for debugging or analysis, and inspecting settings for troubleshooting or auditing your ActivityWatch setup.

To use it with Claude for Desktop, you add the MCP server under the mcpServers section of Claude’s config. If you built from source, point Claude to your local Node.js build path; otherwise, use the published npm package. The server supports a number of tools such as list-buckets, run-query, get-events, and get-settings, each with a set of parameters described in the README. When crafting prompts for Claude, ensure your timeperiods and query statements are combined into a single string within the query array, following the provided formatting guidance to avoid common issues.

Prerequisites

• ActivityWatch installed and running
• Node.js (v14 or higher)
• npm (comes with Node.js) or yarn
• Access to Claude for Desktop or another MCP client

Install from npm (recommended)

1. Install globally (optional):

npm install -g activitywatch-mcp-server

2. Run the server:

activitywatch-mcp-server

Build 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

4. Run the built server (example):

node dist/index.js

Prerequisites for running with Claude

• Ensure Claude is configured to load MCP servers via the mcpServers config (as shown in the README).
• If you’re using a built local server, specify the Node command and path to the built index.js in Claude’s configuration.

Tips and troubleshooting:

• The server connects to ActivityWatch at http://localhost:5600 by default. If you’re running ActivityWatch elsewhere, update the configuration accordingly.
• When using Claude, ensure the timeperiods array is a single string per query (e.g., ["2024-10-28/2024-10-29"]) and that the entire query is contained in one string inside the query array.
• If you encounter connection errors, verify ActivityWatch is running and accessible from the MCP server host. Check CORS or network restrictions if applicable.
• The available tools include: list-buckets (to list buckets with optional type filtering), run-query (to execute AQL statements), get-events (to fetch raw bucket events), and get-settings (to fetch ActivityWatch settings).
• If you customize the server path (when running from source), make sure Claude’s configuration points to the correct executable path and entry file.