umami

English | 한국어

umami-mcp

Umami Analytics v3 API 用の Model Context Protocol サーバーです。 セルフホスト環境でのユーザー名／パスワードまたは API キーによる認証と、Umami Cloud の API キーに対応し、分析、データ収集、管理に加え、ボード、リンク、ピクセル、 セグメント、セッションリプレイ、共有、エクスポート、パフォーマンス、収益などの v3 の機能群を公開します。

このバージョンでは、すべての非公開 Umami ルートに対応しているとは謳いません。ツールは、 Umami 3.4 の API キー認証を含む、ドキュメント化された API に対応しています。 レポートツールでは、Umami 3.4 でも引き続きサポートされる従来のレポート契約を使用します。

要件

• Node.js 20 以降。インストール済みの MCP SDK のランタイム依存関係に適合するバージョン
• Umami v3.3 互換のセルフホストインスタンス（API キー、セッションプロパティのセグメント、アノテーションには 3.4 以降）、または対応するルートが有効になっている Umami Cloud

インストール

npm install -g @mikusnuz/umami-mcp

または、直接実行します。

npx -y @mikusnuz/umami-mcp

設定

セルフホスト

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/umami-mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

UMAMI_URL はインスタンスのオリジンです。末尾に /api を付けても構いませんが、 必須ではありません。

Umami 3.4 以降では、Settings → API keys で API キーを作成し、 UMAMI_USERNAME と UMAMI_PASSWORD を UMAMI_API_KEY に置き換えてください。 UMAMI_MODE を self-hosted に設定すると、デプロイモードを明示的に選択できます。

Umami Cloud

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/umami-mcp"],
      "env": {
        "UMAMI_API_KEY": "your-cloud-api-key"
      }
    }
  }
}

Cloud の管理 API 呼び出しでは、デフォルトで https://api.umami.is/v1 を使用します。ツールのパスは、 セルフホストの /api/... パスから Cloud の /v1/... パスに変換されます。 Cloud のリージョンを明示する必要がある場合は、UMAMI_URL を https://api.umami.is/v1/us または https://api.umami.is/v1/eu に設定してください。 別のホスト名にある Cloud API プロキシを使用する場合は、UMAMI_MODE も cloud に設定してください。

環境変数

変数	必要な場合	説明
UMAMI_MODE	任意	self-hosted または cloud。省略時は自動検出
UMAMI_URL	セルフホスト	インスタンスのオリジン。Cloud では任意
UMAMI_USERNAME	セルフホストの API キーを使用しない場合	ログインユーザー名
UMAMI_PASSWORD	セルフホストの API キーを使用しない場合	ログインパスワード
UMAMI_API_KEY	Cloud。セルフホストの 3.4 以降では任意	Bearer API キー
UMAMI_COLLECTOR_URL	任意	パブリックな収集／共有／ハートビート／レコーダーのルートに使用する別のホスト

Cloud では、コレクターのデフォルトは https://cloud.umami.is です。セルフホストの Umami では、デフォルトは UMAMI_URL です。 UMAMI_URL を指定せずに API キーを設定した場合、または api.umami.is の URL を指定した場合は、Cloud が選択されます。 それ以外の URL を設定すると、API キーを使用している場合でもセルフホストモードが選択されます。

認証とパブリックルート

管理ツールと分析ツールはベアラートークンを送信します。クライアントは、 パスワードを使用する場合、セルフホストインスタンスに遅延ログインし、返された JWT をキャッシュします。 API キーは、どちらのデプロイタイプでもベアラー認証情報として直接送信されます。

パブリックなデータ収集ルートでは、認証情報は不要です。

• send_event、send_identify、send_performance
• batch_events（未加工の JSON 配列、最大 500 件）
• heartbeat、get_share、get_recorder_config

セルフホストのログインで二要素認証が必要と報告された場合は、現在有効な TOTP またはバックアップコードを使って complete_two_factor_login を呼び出し、その後、元のツールを再試行してください。 セルフホストの Umami では、セットアップツールとポリシーツールも公開されます。

Umami Cloud は、API キー経由で /me/password、/users、/users/* を公開していません。 これらのツールはセルフホストインスタンス用です。

ツールグループ

分野	代表的なツール
Webサイト	list_websites、CRUD、リセット、ユーザー／チームへの移管、リプレイ設定
アナリティクス	get_stats、get_pageviews、get_metrics、get_events、get_sessions、イベント系列
イベント／セッションデータ	イベント値、フィールド、プロパティ、値、セッションアクティビティ
収集	イベント／ページビュー、識別、パフォーマンス、生のバッチ、リンク／ピクセルイベント
レポート	アトリビューション、内訳、ファネル、目標、ヒートマップ、ジャーニー、パフォーマンス、リテンション、収益、UTM に対応する保存済みレポートの CRUD と run_report
ボード	一覧表示、CRUD、複製、チームボード
リンクとピクセル	一覧表示、CRUD、チャート、収集イベント
セグメント	セグメント／コホートの一覧表示と CRUD
アノテーション（3.4+）	list_annotations、get_annotation、create_annotation、update_annotation、delete_annotation
リプレイ	レコーダー設定、リプレイ一覧／詳細、保存済みリプレイ、セッションリプレイ
共有とエクスポート	公開共有の解決、管理対象のWebサイト共有、更新／削除、CSV ZIP エクスポート
収益	統計、チャート、指標、収益セッション
ユーザーとチーム	現在の管理者ユーザーとチームのメンバーシップ／移管ルート
2FA	ログイン完了、登録、無効化、管理者による適用ポリシー
リアルタイム	get_realtime

完全な機械可読リストとスキーマを確認するには、MCP の tools/list を使用してください。

v3 の重要な仕様

• ページビューはイベントの name を指定せず、{ "type": "event" } として送信します。従来の pageview タイプは無効になりました。
• /api/batch はイベントオブジェクトを { "events": [...] } ではなく、生の配列として受け取ります。このツールは Umami の processed、errors、項目ごとの details フィールドを返し、一部の項目で失敗した場合は MCP エラー結果として示します。
• Umami の要件に従い、コレクターへの呼び出しではボットではない安定した User-Agent ヘッダーを設定します。send_event とバッチ項目では、ペイロードに訪問者の userAgent と信頼できるサーバー側の ip も指定できます。
• アナリティクスの URL フィルターとページ指標では path を使用します。従来の url 指標は削除されました。ホストの集計には hostname を使用します。
• 対応する名前付きオプションが省略されていても、追加の filters は保持されます。名前付きオプションが明示的に指定されている場合は、filters より優先されます。
• セグメントの作成と更新では、filters、sessionPropertyFilters、match、dateRange、action を使用できます。セッションプロパティのデータ型は、1=文字列、2=数値、3=ブール値、4=日付、5=配列です。コホートではセッションプロパティのフィルターは使用できません。不明なネストフィールドは黙って破棄されず、拒否されます。
• アノテーションには Umami 3.4+ と、書き込みのためのWebサイト編集権限が必要です。ISO 日付またはタイムスタンプと、1～500 文字のメモを指定し、任意で allDay を指定します（既定値は true）。更新では3つのフィールドすべてを置き換えます。一覧の日付フィルターでは、startAt と endAt の両方をミリ秒単位で指定する必要があります。古いサーバーでは 404 が返されることがあります。
• 対応する時間単位は minute、hour、day、month、year です。
• get_event_series と get_sessions_weekly には IANA タイムゾーンが必要です。
• list_reports には websiteId が必要です。レポートの実行では { websiteId, type, filters, parameters } を送信します。
• チームのWebサイトメンバーシップは transfer_website を通じて変更します。削除されたチームWebサイトの POST／DELETE ルートは公開されていません。

開発

npm install
npm test

npm test は TypeScript サーバーをビルドし、Cloud／セルフホスト可能な URL と認証の動作をチェックし、生の公開バッチリクエストと 2FA ログインフローを検証し、主要な MCP スキーマを確認します。

Official references

• Umami API overview
• Authentication
• Cloud API keys
• Sending statistics
• Website statistics
• Reports
• Cloud/API changelog
• Umami v3.4.0 server source
• Report API compatibility

License

MIT