ActivityWatch MCP Server

What is ActivityWatch MCP Server?

A Model Context Protocol server that connects to ActivityWatch, allowing LLMs like Claude to interact with your time tracking data.

How to use ActivityWatch MCP Server?

Install via npm or build from source. Configure the server in your MCP client (e.g., Claude for Desktop) by adding it to the client’s config file. ActivityWatch must be running on http://localhost:5600.

Key features of ActivityWatch MCP Server?

• List all ActivityWatch buckets
• Run AQL queries against time data
• Get raw events from any bucket
• Access ActivityWatch configuration settings

Use cases of ActivityWatch MCP Server?

• Get a summary of which applications you used most today
• View your browsing history by time spent per website
• Check how much time you spent in productivity apps
• Retrieve current ActivityWatch settings or a specific setting
• Debug your ActivityWatch data by fetching raw bucket events

FAQ from ActivityWatch MCP Server

What are the prerequisites to use this server?

ActivityWatch must be installed and running, Node.js v14 or higher is required, and an MCP‑compatible client (e.g., Claude for Desktop) is needed.

Why does the server show connection errors?

If ActivityWatch is not running or is not accessible at http://localhost:5600, the server will report connection errors. Ensure ActivityWatch is started and reachable.

How do I fix query errors when using the MCP server?

Check your AQL syntax, verify bucket IDs are correct, confirm the timeperiods contain data, and review ActivityWatch logs for details. Common formatting issues include splitting query statements into separate array elements instead of one string.

What is the correct format for queries?

All query statements must be in a single string inside the query array. Example: ["events = query_bucket('bucket_id'); RETURN = events;"]. timeperiods should be an array of date‑range strings like ["2024-10-28/2024-10-29"].

How does the server connect to ActivityWatch?

The server connects to the ActivityWatch API at http://localhost:5600 by default. If your ActivityWatch instance uses a different host or port, modify the source code.