ActivityWatch MCP-Server

Ein Model Context Protocol (MCP)-Server, der eine Verbindung zu ActivityWatch herstellt und es LLMs wie Claude ermöglicht, mit Ihren Zeiterfassungsdaten zu interagieren.

Funktionen

• Buckets auflisten: Alle verfügbaren ActivityWatch-Buckets anzeigen

• Abfragen ausführen: Leistungsstarke AQL-Abfragen (ActivityWatch Query Language) ausführen

• Rohdaten abrufen: Ereignisse direkt aus jedem Bucket abrufen

• Einstellungen abrufen: Auf ActivityWatch-Konfigurationseinstellungen zugreifen

Related MCP server: Amplitude MCP Server

Installation

Sie können den ActivityWatch MCP-Server entweder über npm installieren oder selbst erstellen.

Installation über npm (bald verfügbar)

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

# Or install locally
npm install activitywatch-mcp-server

Aus dem Quellcode erstellen

1. Klonen Sie dieses Repository:

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

2. Abhängigkeiten installieren:

   npm install

3. Das Projekt erstellen:

   npm run build

Voraussetzungen

• ActivityWatch installiert und aktiv

• Node.js (v14 oder höher)

• Claude for Desktop (oder ein anderer MCP-Client)

Verwendung

Verwendung mit Claude for Desktop

1. Öffnen Sie Ihre Konfigurationsdatei für Claude for Desktop:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Fügen Sie die MCP-Server-Konfiguration hinzu:

   {
   "mcpServers": {
       "activitywatch": {
       "command": "activitywatch-mcp-server",
       "args": []
       }
   }
   }

   Wenn Sie aus dem Quellcode erstellt haben, verwenden Sie:

   {
   "mcpServers": {
       "activitywatch": {
       "command": "node",
       "args": ["/path/to/activitywatch-mcp-server/dist/index.js"]
       }
   }
   }

3. Starten Sie Claude for Desktop neu

4. Suchen Sie nach dem MCP-Symbol in der Benutzeroberfläche von Claude, um zu bestätigen, dass es funktioniert

Verwendung eines rootless Podman-Containers unter Linux mit dem Gemini CLI

Stellen Sie sicher, dass Sie das Image zuerst erstellen mit:

version=$(npm pkg get version | tr -d '"')
podman build . -t activitywatch-mcp-server:${version}

Dieses Beispiel verwendet die Überschreibung für den Fall, dass Activity Watch nicht unter 127.0.0.1 verfügbar ist (siehe nächster Abschnitt). Falls nicht erforderlich, können Sie die Umgebungsvariable AW_API_BASE weglassen.

{
  "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"
      }
    }
  }
}

ActivityWatch-Server Host/Port überschreiben

Wenn Sie diesen MCP-Server beispielsweise innerhalb eines Containers vom Windows Subsystem for Linux ausführen möchten, ist der unter Windows laufende AW-Server nicht unter 127.0.0.1 verfügbar. Um die Standard-Localhost-Verbindung zu überschreiben, verwenden Sie die Umgebungsvariable AW_API_BASE oder das Flag --aw-api-base, wie unten gezeigt:

# 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

HINWEIS: Der AW-Server ist möglicherweise wählerisch bezüglich des Namens, der für die Verbindung verwendet wird, aber er akzeptiert einen Namen, der dem Computernamen entspricht, auf dem er läuft, mit einem .local-Suffix.

Beispielabfragen

Hier sind einige Beispielabfragen, die Sie in Claude ausprobieren können:

• Alle Buckets auflisten: "Welche ActivityWatch-Buckets habe ich?"

• Zusammenfassung der Anwendungsnutzung abrufen: "Kannst du mir zeigen, welche Anwendungen ich heute am meisten genutzt habe?"

• Browserverlauf anzeigen: "Auf welchen Websites habe ich heute die meiste Zeit verbracht?"

• Produktivität prüfen: "Wie viel Zeit habe ich heute in Produktivitäts-Apps verbracht?"

• Einstellungen anzeigen: "Was sind meine ActivityWatch-Einstellungen?" oder "Kannst du eine bestimmte Einstellung in ActivityWatch überprüfen?"

Verfügbare Tools

list-buckets

Listet alle verfügbaren ActivityWatch-Buckets mit optionaler Typfilterung auf.

Parameter:

• type (optional): Buckets nach Typ filtern (z. B. "window", "web", "afk")

• includeData (optional): Bucket-Daten in die Antwort einbeziehen

run-query

Führt eine Abfrage in der Abfragesprache von ActivityWatch (AQL) aus.

Parameter:

• timeperiods: Abzufragende Zeiträume als Array von Strings formatiert. Für Datumsbereiche das Format verwenden: ["2024-10-28/2024-10-29"]

• query: Array von Abfrageanweisungen in der ActivityWatch Query Language, wobei jedes Element eine vollständige Abfrage mit durch Semikolons getrennten Anweisungen ist

• name (optional): Name für die Abfrage (wird für das Caching verwendet)

WICHTIG: Jeder Abfrage-String sollte eine vollständige Abfrage mit mehreren durch Semikolons getrennten Anweisungen enthalten.

Beispiel-Anfrageformat:

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

Beachten Sie, dass:

• timeperiods vorformatierte Datumsbereiche mit Schrägstrichen haben sollten

• Jedes Element im query-Array eine vollständige Abfrage mit allen Anweisungen ist

get-events

Ruft Rohdaten aus einem ActivityWatch-Bucket ab.

Parameter:

• bucketId: ID des Buckets, aus dem Ereignisse abgerufen werden sollen

• start (optional): Startdatum/-zeit im ISO-Format

• end (optional): Enddatum/-zeit im ISO-Format

• limit (optional): Maximale Anzahl der zurückzugebenden Ereignisse

get-settings

Ruft ActivityWatch-Einstellungen vom Server ab.

Parameter:

• key (optional): Einen bestimmten Einstellungsschlüssel anstelle aller Einstellungen abrufen

Beispiele für die Abfragesprache

ActivityWatch verwendet eine einfache Abfragesprache. Hier sind einige gängige Muster:

// Get window events
window_events = query_bucket(find_bucket("aw-watcher-window_"));
RETURN = window_events;

// Get only when not AFK
afk_events = query_bucket(find_bucket("aw-watcher-afk_"));
not_afk = filter_keyvals(afk_events, "status", ["not-afk"]);
window_events = filter_period_intersect(window_events, not_afk);
RETURN = window_events;

// Group by app
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);

// Filter by app name
window_events = query_bucket(find_bucket("aw-watcher-window_"));
code_events = filter_keyvals(window_events, "app", ["Code"]);
RETURN = code_events;

Konfiguration

Der Server verbindet sich standardmäßig mit der ActivityWatch-API unter http://localhost:5600. Wenn Ihre ActivityWatch-Instanz auf einem anderen Host oder Port läuft, können Sie dies wie im Abschnitt "ActivityWatch-Server Host/Port überschreiben" oben beschrieben überschreiben.

Fehlerbehebung

ActivityWatch läuft nicht

Wenn ActivityWatch nicht läuft, zeigt der Server Verbindungsfehler an. Stellen Sie sicher, dass ActivityWatch läuft und unter der angegebenen Host-/Port-Adresse erreichbar ist (http://localhost:5600, sofern Sie es nicht überschrieben haben).

Abfragefehler

Wenn Sie auf Abfragefehler stoßen:

1. Überprüfen Sie Ihre Abfragesyntax

2. Stellen Sie sicher, dass die Bucket-IDs korrekt sind

3. Überprüfen Sie, ob die Zeiträume Daten enthalten

4. Überprüfen Sie die ActivityWatch-Protokolle auf weitere Details

Probleme mit der Abfrageformatierung in Claude/MCP

Wenn Claude Fehler meldet, wenn Abfragen über diesen MCP-Server ausgeführt werden, liegt dies wahrscheinlich an Formatierungsproblemen. Stellen Sie sicher, dass Ihre Abfrage in Ihren Prompts genau dieses Format einhält:

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

Allgemeine Probleme:

• Zeiträume nicht korrekt formatiert (sollten "Start/Ende" als einzelner String innerhalb eines Arrays sein)

• Abfrageanweisungen in separate Array-Elemente aufgeteilt, anstatt in einem String kombiniert zu werden

Das häufigste Formatierungsproblem

Der häufigste Fehler tritt auf, wenn Claude jede Abfrageanweisung in ein eigenes Array-Element aufteilt, wie hier:

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

Dies ist FALSCH. Stattdessen sollten alle Anweisungen in einem einzigen String innerhalb des Arrays stehen:

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

Beim Prompten von Claude

Wenn Sie Claude prompten, seien Sie sehr explizit bezüglich des Formats und verwenden Sie Beispiele. Sagen Sie zum Beispiel:

"Führe eine Abfrage aus mit timeperiods als ["2024-10-28/2024-10-29"] und query als ["statement1; statement2; RETURN = result;"]. Wichtig: Stelle sicher, dass ALLE Abfrageanweisungen in einem einzigen String innerhalb des Arrays stehen, nicht in separate Array-Elemente aufgeteilt."

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull Request einzureichen.

Lizenz

MIT