ActivityWatch MCP Server: Integrate Time Tracking Data into AI Applications

Overview: What is ActivityWatch MCP Server?

The ActivityWatch MCP Server is designed to bridge the gap between activity tracking tools and advanced AI applications such as Claude Desktop, Continue, Cursor, and other MCP clients. By leveraging Model Context Protocol (MCP), this server allows AI systems to interact with detailed time tracking data from ActivityWatch. This integration provides a powerful way for AI applications to analyze user behavior, provide insights, or even adapt their functionality based on real-time activity data.

Key Benefits

• Enhanced Data Insights: MCP enables AI applications to access granular and structured ActivityWatch data, providing richer input for insights and analytics.
• Improved User Engagement: By integrating with AI applications like Claude Desktop, users can get personalized recommendations or suggestions based on their activity patterns.
• Flexibility: This server supports multiple AI tools, making it versatile for different use cases across various applications.

🔧 Core Features & MCP Capabilities

The ActivityWatch MCP Server offers several key functionalities that cater to the needs of both AI applications and end-users:

Data Retrievable Functions

1. List Buckets: View all available buckets in ActivityWatch.
2. Run Queries: Execute powerful AQL (ActivityWatch Query Language) queries directly from an AI application like Claude Desktop.
3. Get Raw Events: Retrieve events directly from any bucket for detailed analysis.
4. Get Settings: Access and modify the configuration settings of ActivityWatch.

Example Use Cases

• Bucket Management: List all your buckets to understand what data sources you are tracking.
• Query Execution: Run complex queries like finding top applications used in a specific period.
• Event Retrieval: Fetch detailed event logs for further analysis.
• Settings Access: Modify configuration settings to fine-tune how ActivityWatch operates.

MCP Protocol Flow

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

Data Architecture

graph TD
    A[AI Application] --> B[MCP Client]
    B --> C[MCP Protocol Layer]
    C --> D[MCP Server]
    D --> E[ActivityWatch API Endpoint]
    E --> F[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#f8d7da

⚙️ MCP Architecture & Protocol Implementation

The core architecture of the ActivityWatch MCP Server revolves around efficiently handling AI client requests and translating them into actionable data through Model Context Protocol (MCP). Key components include:

Endpoint Configuration

By default, the server connects to the ActivityWatch API at http://localhost:5600. However, this can be adjusted in the source code for custom deployment scenarios.

# Example environment setup
API_URL=http://remote_server:5600

Commands & Parameters

The server supports various commands and parameters to interact with ActivityWatch:

• list-buckets: Lists all available buckets.
• run-query: Executes AQL queries.
• get-events: Fetches raw events from a specified bucket.
• get-settings: Accesses ActivityWatch settings.

🚀 Getting Started with Installation

To get started with the ActivityWatch MCP Server, you can choose between installing it via npm or building it from source. Each method is detailed below:

Installing from npm (coming soon)

# Global installation
npm install -g activitywatch-mcp-server

# Or local installation
npm install activitywatch-mcp-server

Building 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
   

💡 Key Use Cases in AI Workflows

Real-world scenarios highlight the versatility of integrating ActivityWatch MCP Server with various AI applications:

Scenario 1: Productivity Analysis

• Problem: A company wants to analyze employee productivity based on application usage.
• Solution: Set up ActivityWatch to track all desktop activities and leverage the ActivityWatch MCP Server to query this data. Use Claude Desktop or a similar tool to generate productivity reports.

Scenario 2: Personalized Learning Suggestions

• Problem: An educational platform aims to provide personalized learning recommendations based on user activity.
• Solution: Deploy an AI application connected to ActivityWatch, configured through the MCP server, to receive and analyze real-time data. This allows for tailored learning experiences and feedback loops.

🔌 Integration with MCP Clients

Example Configuration JSON

To integrate with Claude Desktop or any other MCP client:

{
  "mcpServers": {
    "activitywatch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-activitywatch"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

📊 Performance & Compatibility Matrix

The ActivityWatch MCP Server supports multiple AI clients, as shown in the compatibility matrix:

MCP Client	Resources	Tools	Prompts	Status
Claude Desktop	✅	✅	✅	Full Support
Continue	✅	✅	✅	Full Support
Cursor	❌	✅	❌	Tools Only

🛠️ Advanced Configuration & Security

Environment Setup

Ensure that the ActivityWatch server is running and accessible at http://localhost:5600 by default. If configured otherwise, modify your server environment file:

API_URL=http://remote_server:5600

Sample Configuration Code

{
  "mcpServers": {
    "activitywatch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-activitywatch"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Security Best Practices

• API Key Authentication: Use a secure API key for client-server communication.
• Data Encryption: Encrypt sensitive data in transit and at rest.

❓ Frequently Asked Questions (FAQ)

Q1: What is the difference between using npm and building from source?

A1: Installing via npm provides a faster setup but may not include all customization options available in a built-from-source environment. Building from source allows for more flexibility, especially when deploying to custom environments.

Q2: Can this server be used with other AI clients besides those listed?

A2: While the MCP client compatibility matrix indicates full support for Claude Desktop and Continue, users can explore compatibility with additional AI applications by configuring their own environments.

Q3: How do I troubleshoot connectivity issues between the AI application and the ActivityWatch MCP Server?

A3: Common troubleshooting steps include verifying API endpoint URLs, checking network configurations, and ensuring that required dependencies are correctly installed. Logging network requests from both ends can provide insights into connection problems.

Q4: Is it possible to customize query templates directly in the server code?

A4: Yes, you can modify the codebase to add or alter query templates for more specific use cases. This customization process is detailed in the documentation provided with the project.

Q5: How does this server enhance AI applications compared to standalone tools?

A5: By integrating ActivityWatch data into AI workflows, this server provides richer datasets and real-time insights that can significantly improve the accuracy and effectiveness of AI-driven decision-making processes.

👨‍💻 Development & Contribution Guidelines

Contributing to the development of the ActivityWatch MCP Server is encouraged. Developers interested in contributing should familiarize themselves with the project's codebase and follow established guidelines:

1. Fork the Repository
   • Clone the repository from GitHub.
2. Create a Pull Request
   • Commit changes according to the established coding conventions.
3. Contribute Code
   • Add features, fix bugs, or improve documentation as per the project's needs.

🌐 MCP Ecosystem & Resources

For more information and resources related to Model Context Protocol (MCP) and its integrations, visit the official MCP documentation and community forums:

• MCP Documentation
• Community Forum

Conclusion

The ActivityWatch MCP Server is a powerful tool for integrating time tracking data with AI applications. Its flexible architecture, comprehensive feature set, and compatibility across various tools make it an invaluable component in enhancing the functionality and insights of advanced AI systems.

By leveraging this server, developers can create more sophisticated and data-driven AI solutions that provide deeper insights into user behavior and preferences.