ActivityWatch MCP サーバー

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

機能

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

• クエリの実行: 強力な AQL (ActivityWatch Query Language) クエリを実行

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

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

Related MCP server: Paprika SQL 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 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

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

クエリの例

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

• すべてのバケットを一覧表示: "What ActivityWatch buckets do I have?"

• アプリケーション使用状況の概要を取得: "Can you show me which applications I've used the most today?"

• 閲覧履歴を表示: "What websites have I spent the most time on today?"

• 生産性を確認: "How much time have I spent in productivity apps today?"

• 設定を表示: "What are my ActivityWatch settings?" または "Can you check a specific setting in ActivityWatch?"

利用可能なツール

list-buckets

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

パラメータ:

• type (オプション): 型でバケットをフィルタリング (例: "window", "web", "afk")

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

run-query

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

パラメータ:

• timeperiods: クエリ対象の期間。文字列の配列としてフォーマットします。日付範囲の場合は ["2024-10-28/2024-10-29"] の形式を使用してください

• query: ActivityWatch Query Language によるクエリステートメントの配列。各アイテムはセミコロンで区切られた完全なクエリです

• 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"]
}

これは誤りです。代わりに、すべてのステートメントを配列内の単一の文字列に含める必要があります:

{
 "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 にプロンプトを出すときは、フォーマットについて非常に明示的に指示し、例を使用してください。例えば、次のように伝えます:

"Run a query with timeperiods as ["2024-10-28/2024-10-29"] and query as ["statement1; statement2; RETURN = result;"]. Important: Make sure ALL query statements are in a single string within the array, not split into separate array elements."

貢献

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

ライセンス

MIT

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• activitywatch_get_eventsC
• activitywatch_get_settingsB
• activitywatch_list_bucketsB
• activitywatch_query_examplesB
• activitywatch_run_queryC