ActivityWatch MCP Server

ActivityWatch MCP サーバー

ActivityWatch に接続する Model Context Protocol (MCP) サーバーです。Claude などの LLM が、あなたの時間追跡データを操作できるようにします。

機能

• バケットの一覧表示: 利用可能なすべての ActivityWatch バケットを表示します
• クエリの実行: 強力な AQL (ActivityWatch Query Language) クエリを実行します
• 生イベントの取得: 任意のバケットからイベントを直接取得します
• 設定の取得: ActivityWatch の構成設定にアクセスします

インストール

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 for Desktop を再起動します

4. Claude のインターフェースに MCP アイコンが表示されていることを確認し、動作していることを確かめます

Linux 上の rootless podman コンテナを Gemini CLI で使用する

まず、次のコマンドでイメージをビルドしてください:

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

この例では、Activity Watch が 127.0.0.1 で利用できないためのオーバーライドを使用しています (次のセクションを参照)。不要な場合は、AW_API_BASE 環境変数を省略できます。

{
  "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 サーバーのホスト/ポートのオーバーライド

たとえばコンテナ内など、Windows Subsystem for Linux の内部からこの MCP サーバーを実行したい場合、Windows で実行されている AW サーバーは 127.0.0.1 では利用できません。標準の localhost 接続をオーバーライドするには、以下のように環境変数 AW_API_BASE または --aw-api-base フラグを使用します:

# 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

NOTE: AW サーバーは、接続に使用される名前に対して厳格な場合がありますが、サーバーが実行されているコンピューター名に .local サフィックスを付けた名前は受け入れます。

クエリの例

Claude で試せるクエリの例をいくつか示します:

• すべてのバケットを一覧表示: 「私が持っている ActivityWatch バケットは何ですか?」
• アプリケーションの使用状況の概要を取得: 「今日最も多く使用したアプリケーションを表示してもらえますか?」
• 閲覧履歴の表示: 「今日最も長い時間を費やしたウェブサイトは何ですか?」
• 生産性の確認: 「今日は生産性アプリにどれくらいの時間を費やしましたか?」
• 設定の表示: 「私の ActivityWatch 設定は何ですか?」または「ActivityWatch の特定の設定を確認してもらえますか?」

利用可能なツール

list-buckets

利用可能なすべての ActivityWatch バケットを、任意の型フィルタリング付きで一覧表示します。

パラメータ:

• type (任意): 型でバケットをフィルタリングします (例: "window"、"web"、"afk")
• includeData (任意): レスポンスにバケットデータを含めます

run-query

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 配列の各項目は、すべてのステートメントを含む完全なクエリです

get-events

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

パラメータ:

• bucketId: イベントを取得するバケットの ID
• start（任意）: ISO 形式の開始日時
• end（任意）: ISO 形式の終了日時
• limit（任意）: 返すイベントの最大数

get-settings

サーバーから 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 が実行されていない

ActivityWatch が実行されていない場合、サーバーは接続エラーを表示します。ActivityWatch が実行されており、指定されたホスト/ポートアドレス（上書きしていない限り http://localhost:5600）でアクセス可能であることを確認してください。

クエリエラー

クエリエラーが発生している場合:

1. クエリの構文を確認してください
2. バケット ID が正しいことを確認してください
3. timeperiods にデータが含まれていることを確認してください
4. 詳細については ActivityWatch のログを確認してください

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

Claude がこの MCP サーバーを通じてクエリを実行する際にエラーを報告する場合、それはフォーマットの問題が原因である可能性が高いです。プロンプト内でクエリが次の正確な形式に従っていることを確認してください:

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

よくある問題:

• 期間が正しくフォーマットされていない（配列内の単一の文字列で "start/end" とする必要があります）
• クエリステートメントが 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"]
}

これは正しくありません。代わりに、すべてのステートメントを配列内の 1 つの文字列にまとめる必要があります:

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

Claude にプロンプトを出す場合

Claude にプロンプトを出す際は、形式について非常に明確に指示し、例を使用してください。たとえば、次のように伝えます:

「timeperiods を ["2024-10-28/2024-10-29"]、query を ["statement1; statement2; RETURN = result;"] としてクエリを実行してください。重要: すべてのクエリステートメントを配列内の 1 つの文字列にまとめ、個別の配列要素に分割しないでください。」

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。

ライセンス

MIT