アクティビティウォッチ MCP サーバー

ActivityWatchに接続する Model Context Protocol (MCP) サーバー。これにより、Claude などの LLM が時間追跡データと対話できるようになります。

特徴

• バケットの一覧表示: 利用可能なすべての ActivityWatch バケットを表示します

• クエリの実行: 強力な AQL (ActivityWatch クエリ言語) クエリを実行します。

• 生のイベントを取得: 任意のバケットから直接イベントを取得します

• 設定を取得: ActivityWatch の構成設定にアクセスします

Related MCP server: Amplitude MCP Server

インストール

ActivityWatch MCP サーバーは、npm からインストールすることも、自分でビルドしてインストールすることもできます。

npm からのインストール (近日公開)

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

# Or install locally
npm install activitywatch-mcp-server

ソースから構築

1. このリポジトリをクローンします:

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

2. 依存関係をインストールします:

   npm install

3. プロジェクトをビルドします。

   npm run build

前提条件

• ActivityWatchがインストールされ、実行中

• Node.js (v14以上)

• Claude for Desktop（またはその他のMCPクライアント）

使用法

Claude for Desktop と併用

1. Claude for Desktop の構成ファイルを開きます。

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

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

2. MCP サーバー構成を追加します。

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

ソースからビルドした場合は、以下を使用します。

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

3. デスクトップ版のClaudeを再起動する

4. クロードのインターフェースでMCPアイコンを探して、それが機能していることを確認してください。

クエリの例

Claude で試すことができるクエリの例を次に示します。

• すべてのバケットを一覧表示します: 「どのような ActivityWatch バケットがありますか?」

• アプリケーションの使用状況の概要を取得する:「今日最も使用したアプリケーションを表示できますか?」

• 閲覧履歴の表示:「今日最も時間を費やしたウェブサイトはどれですか?」

• 生産性をチェックする: 「今日、生産性向上アプリにどれくらいの時間を費やしましたか?」

• 設定の表示:「ActivityWatch の設定は何ですか?」または「ActivityWatch で特定の設定を確認できますか?」

利用可能なツール

リストバケット

オプションのタイプ フィルタリングを使用して、利用可能なすべての ActivityWatch バケットを一覧表示します。

パラメータ:

• type （オプション）：バケットをタイプ別にフィルタリングします（例：「window」、「web」、「afk」）

• includeData (オプション): レスポンスにバケットデータを含める

クエリ実行

ActivityWatch のクエリ言語 (AQL) でクエリを実行します。

パラメータ:

• timeperiods : クエリ対象となる期間を文字列の配列で指定します。日付範囲を指定する場合は、 ["2024-10-28/2024-10-29"]という形式を使用します。

• query : ActivityWatch クエリ言語のクエリステートメントの配列。各項目はセミコロンで区切られたステートメントを含む完全なクエリです。

• name (オプション): クエリの名前 (キャッシュに使用)

重要: 各クエリ文字列には、セミコロンで区切られた複数のステートメントを含む完全なクエリが含まれている必要があります。

リクエスト形式の例:

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

ご了承ください：

• timeperiodsスラッシュでフォーマットされた日付範囲が必要です

• query配列の各項目は、すべてのステートメントを含む完全なクエリです。

取得イベント

ActivityWatch バケットから生のイベントを取得します。

パラメータ:

• bucketId : イベントを取得するバケットのID

• start (オプション): ISO形式での開始日時

• end (オプション): ISO 形式の終了日時

• limit (オプション): 返されるイベントの最大数

設定の取得

サーバーから ActivityWatch 設定を取得します。

パラメータ:

• key （オプション）：すべての設定ではなく、特定の設定キーを取得します

クエリ言語の例

ActivityWatch はシンプルなクエリ言語を使用します。一般的なパターンをいくつかご紹介します。

// 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;

構成

サーバーはデフォルトでhttp://localhost:5600 ActivityWatch API に接続します。ActivityWatch インスタンスが別のホストまたはポートで実行されている場合は、ソースコードでこれを変更できます。

トラブルシューティング

アクティビティウォッチが動作しない

ActivityWatch が実行されていない場合、サーバーに接続エラーが表示されます。ActivityWatch が実行されており、 http://localhost:5600でアクセスできることを確認してください。

クエリエラー

クエリ エラーが発生した場合:

1. クエリ構文を確認してください

2. バケットIDが正しいことを確認してください

3. 期間にデータが含まれていることを確認する

4. 詳細についてはActivityWatchログを確認してください

Claude/MCP クエリフォーマットの問題

Claude がこの MCP サーバー経由でクエリを実行した際にエラーを報告した場合、フォーマットの問題が原因である可能性があります。プロンプトでクエリが以下の形式に正確に従っていることを確認してください。

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

よくある問題:

• 期間の形式が正しくありません (配列内の単一の文字列に「開始/終了」とする必要があります)

• クエリステートメントは、1つの文字列に結合されるのではなく、個別の配列要素に分割されます。

最も一般的な書式設定の問題

最もよくあるエラーは、Claude が次のように各クエリ ステートメントを独自の配列要素に分割する場合です。

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

これは正しくありません。すべてのステートメントは配列内の単一の文字列にする必要があります。

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

クロードに促すとき

クロードに指示を出す際は、形式を明確にし、例を挙げて指示してください。例えば、次のように言ってください。

期間を["2024-10-28/2024-10-29"] 、クエリを["statement1; statement2; RETURN = result;"]として実行します。重要: すべてのクエリステートメントが配列内の単一の文字列に含まれており、個別の配列要素に分割されていないことを確認してください。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

マサチューセッツ工科大学