ActivityWatchCAUTION
Model Context Protocol server for ActivityWatch time tracking data
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
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
- Clone this 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
Prerequisites
- ActivityWatch installed and running
- Node.js (v14 or higher)
- Claude for Desktop (or any other MCP client)
Usage
Using with Claude for Desktop
- Open your Claude for Desktop configuration file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- 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/activitywatc2f744a42f846OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add activitywatch-mcp-server -- npx -y [email protected]
{
"mcpServers": {
"activitywatch-mcp-server": {
"command": "npx",
"args": [
"-y",
"[email protected]"
]
}
}
}Exposed tools (10)
6 read · 3 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
activitywatch_add_category | write | Add a new category to ActivityWatch. The category will be appended to the existing list. |
activitywatch_delete_category | destructive | Delete an ActivityWatch category by its name path. |
activitywatch_get_categories | read | Get all ActivityWatch categories (classification rules). Returns the list of categories with their regex rules used to classify window events. |
activitywatch_get_events | read | Get raw events from an ActivityWatch bucket |
activitywatch_get_settings | read | Get ActivityWatch settings. Can retrieve all settings or a specific key if provided. |
activitywatch_get_uncategorized_events | read | Fetch window events that have NOT been matched by any category rule, grouped and sorted by total duration. |
activitywatch_list_buckets | read | List all ActivityWatch buckets with optional type filtering |
activitywatch_query_examples | read | Get examples of properly formatted queries for the ActivityWatch MCP server |
activitywatch_run_query | write | Run a query in ActivityWatch |
activitywatch_update_category | write | Update an existing ActivityWatch category by its name path. Replaces the matching category with new values. |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (5 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (6)
.DS_Store
activitywatch_delete_category
.DS_Store
@modelcontextprotocol/sdk, axios, zod, @jest/globals, @types/jest, @types/node, cross-env, jest
load_dotenv() # load environment variables from .env
curl -LsSf https://astral.sh/uv/install.sh | sh
Gates applied: no_behavioural_pass.
2f744a42f846full audit observations/trust-audit/mcp-server/8bitgentleman__activitywatch.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | 2f744a42f846 | CAUTION | B | 89 | first audit |
Questions
What is the ActivityWatch MCP server?
Model Context Protocol server for ActivityWatch time tracking data
What tools does ActivityWatch expose?
10 in total: 6 read-only, 3 that write, and 1 that can delete or overwrite (activitywatch_delete_category). Every one is listed on this page with its risk.
Is ActivityWatch safe to connect to an agent?
With care. The audit graded it B (89/100) and found 6 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does ActivityWatch need?
No credential environment variables were found in its source, so it appears to need none.
How does ActivityWatch run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as activitywatch-mcp-server at 1.2.1.
How current is this page?
The grade is for one exact copy of the source (2f744a42f846), read on 2026-10-07. The repository is watched and re-audited when it changes.