Activitywatch MCP Server

🚀 ActivityWatch MCP Server

ActivityWatch MCP Server allows interaction with ActivityWatch through AI tools like Claude to query and analyze user activity data.

🚀 Quick Start

The ActivityWatch MCP Server enables seamless interaction with ActivityWatch, facilitating the query and analysis of user activity data via AI tools such as Claude.

✨ Features

• Collect Activity Data: Gather detailed user activity data from ActivityWatch.
• Time Range Filtering: Support data queries within specified time periods.
• Multi-Condition Filtering: Filter data based on conditions such as applications and status (e.g., idle or not).
• Data Aggregation: Aggregate and summarize activity data by application or other attributes.

📦 Installation

Install from npm

npm install activitywatch-mcp-server

Build and Install from Source Code

1. Clone the repository:

   git clone https://github.com/yourusername/activitywatch-mcp-server.git
   cd activitywatch-mcp-server
   

2. Install dependencies:

   npm install
   

3. Start the service:

   npm start
   

Prerequisites

• Node.js and npm are installed.
• The ActivityWatch server is running, with the default address being http://localhost:5600.

💻 Usage Examples

Connect to ActivityWatch

By default, it connects to http://localhost:5600. If you need to change it, modify the configuration in the source code.

Example Queries

Get Browser Activity

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["browser_events = query_bucket('aw-watcher-web'); RETURN = browser_events;"]
}

Filter Idle Status

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": [
    "afk_bucket = query_bucket('aw-watcher-afk_');",
    "not_afk_events = filter_keyvals(afk_bucket, 'status', ['not-afk']);",
    "window_events = query_bucket('aw-watcher-window_');",
    "final_events = filter_period_intersect(window_events, not_afk_events);",
    "RETURN = final_events;"
  ]
}

Query Language Examples

Get Window Events

window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;

Group by Application

window_events = query_bucket(find_bucket("aw-watcher-window_"));
events_by_app = merge_events_by_keys(window_events, ["app"]);
RETURN = sort_by_duration(events_by_app);

Configuration

The default connection address is http://localhost:5600. If you need to change it, modify the corresponding configuration in the code.

Troubleshooting

ActivityWatch Not Running

If the service encounters connection errors, ensure that ActivityWatch is started and accessible via http://localhost:5600.

Query Errors

• Check the query syntax.
• Confirm that the bucket ID is correct.
• Verify that there is data within the specified time period.
• Check the ActivityWatch logs for more information.

Important Note

When running queries through Claude, ensure that the JSON format is correct. In particular, place all query statements in a single string:

{
  "timeperiods": ["2024-10-28/2024-10-29"],
  "query": ["statement1; statement2; RETURN = result;"]
}

Contribution

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT