8bitgentleman/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)
bash
# Global installation
npm install -g activitywatch-mcp-server
# Or install locally
npm install activitywatch-mcp-server
### Building from Source
1. Clone this repository:
bash
git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git
cd activitywatch-mcp-server
2. Install dependencies:
bash
npm install
3. Build the project:
bash
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
1. Add the MCP server configuration:
json
"mcpServers": {
"activitywatch": {
"command": "activitywatch-mcp-server",
"args": []
If you built from source, use:
json
"mcpServers": {
"activitywatch": {
"command": "node",
"args": ["/path/to/activitywatch-mcp-server/dist/index.js"]
1. Restart Claude for Desktop
1. 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:
sh
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.
json
"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:
sh
# 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?"