umami-mcp-server

Umami Analytics 向けの MCP サーバーです。読み取り専用で、Umami Cloud とセルフホストインスタンスの両方で動作します。エポックミリ秒や UUID ではなく、last_month のようなレンジや example.com のようなサイト名で指定します。

ウェブサイトの探索、トラフィック統計、時系列、ランキング内訳、カスタムイベント、個別セッション、1回の呼び出しでの完全なレポート、ウェブサイト・ユーザー・チームの完全な管理者 CRUD、クライアントオンボーディングの複合ツール、そしてそれ以外の Umami API にアクセスするための素の GET エスケープハッチまで、25 本のツールを備えています。

管理者ツール（ユーザー・チーム・ウェブサイトの作成、および各種削除）には、管理者ログインまたは管理者 API キーを持つセルフホスト Umami が必要です。Umami Cloud は API 経由でユーザーやチームの管理を公開していないため、Cloud に向けて使うと紛らわしい 404 ではなく明確なエラーが返ります。

インストール

npm install
npm run build

Related MCP server: Plausible MCP

設定

.env.example をコピーし、2 つの認証方法のうちいずれかを記入します。

Umami Cloud

Settings の API keys からキーを作成してください。

セルフホスト

共通

接続する

Claude Desktop または Claude Code

claude_desktop_config.json に追加するか、claude mcp add を実行します:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_TIMEZONE": "America/New_York",
        "UMAMI_DEFAULT_WEBSITE": "example.com"
      }
    }
  }
}

セルフホストインスタンスの場合は、UMAMI_BASE_URL と、API キーまたはユーザー名とパスワードのペアのどちらかを設定します。

MCP Inspector

UMAMI_API_KEY=your-key npm run inspect

ツール

アナリティクス（読み取り専用）

管理者: ウェブサイト（セルフホスト、管理者ログインまたはキー）

管理者: ユーザー（セルフホスト、管理者ログインまたはキー）

管理者: チーム（セルフホスト、管理者ログインまたはキー）

プロビジョニング

エスケープハッチ

すべてのデータツールは response_format を受け付けます。読みやすい要約には markdown、構造化されたペイロードには json を指定します。破壊的ツール（reset、delete、remove）はすべて必須の confirm: true 引数を取ります。これがないと呼び出しは拒否されます。他に確認手順はないため、この引数が「引き返せない地点」です。

日付レンジ

range には以下のいずれかを渡します:

• 相対: 30m, 24h, 7d, 4w, 3mo, 1y

• 名前付き: today, yesterday, this_week, last_week, this_month, last_month, this_year, last_year, mtd, ytd, all_time

または start_date と end_date を YYYY-MM-DD、完全な ISO 8601 タイムスタンプ、エポックミリ秒で渡します。明示的な日付は range をオーバーライドします。日付境界は UMAMI_TIMEZONE、または呼び出しごとの timezone 引数に従います。

フィルター

ほとんどのツールは、クエリをセグメントする filters オブジェクトを受け取ります:

{ "country": "US", "device": "mobile", "path": "/pricing" }

サポートされているキー: path、referrer、title、query、browser、os、device、country、region、city、language、hostname、tag、event、distinctId、utmSource、utmMedium、utmCampaign、utmContent、utmTerm、segment、cohort。

内訳のディメンション

umami_get_metrics と umami_traffic_report の breakdowns 引数で使用できます: path、entry、exit、title、query、referrer、channel、domain、country、region、city、browser、os、device、language、screen、event、hostname、tag、distinctId。

例

接続し終えたら、自然な言葉で質問できます:

• 「先月のサイトの調子は前月と比べてどうでしたか？」 → range=last_month を指定した umami_get_stats

• 「直近 30 日間のアナリティクスの全体像を見せて」 → umami_traffic_report

• 「どのランディングページが最も直帰率が悪いですか？」 → type=entry と expanded=true を指定した umami_get_metrics

• 「今週の問い合わせフォーム送信は何件ですか？」 → event=contact-form-submit を指定した umami_get_events_series

• 「フロリダのモバイル訪問者にとって多いページを表示して」 → type=path と filters={ device: "mobile", region: "US-FL" } を指定した umami_get_metrics

• 「そのセッションは実際にサイトで何をしましたか？」 → umami_list_sessions、続けて umami_get_session

• 「新しいクライアントのトラッキングと専用チームを設定し、jordan を追加して」 → website_name、domain、team_name、grant_user_id を指定した umami_onboard_client

• 「サイトを公開する前にテストデータを削除したい」 → confirm=true を指定した umami_reset_website

設計メモ

• Webサイトの解決。 どのツールもwebsite引数でUUID、名前、またはドメインを受け付けます。名前とドメインは60秒間キャッシュされたWebサイト一覧と照合され、黙って誤った推測をするのではなく、明確なあいまいさエラーを返します。Webサイトの作成・更新・削除を行うと、そのキャッシュは即座に更新されます。

• リプレイ／ヒートマップの完全な設定（トグルのみではありません）。 umami_update_websiteは、UmamiのreplayConfigが受け入れるすべてのフィールドを公開します。有効化フラグ、リプレイとヒートマップでそれぞれ独立したサンプルレート、PIIマスクレベル、ブロックセレクタ、最大録画時間です。Umami公式ドキュメントはmaxDurationの単位について不整合があります（ある例はミリ秒、別の例は秒を示しています）。推測で済ませるのではなく、umami_get_recorder_configはトラッカー自体が呼び出すのと同じ公開エンドポイントを読み取るため、どちらのドキュメント例に頼らなくても、保存後に実際に有効な値を確認できます。

• 導出メトリクス。 Umamiは生のbouncesとtotaltimeのカウントを返します。直帰率、訪問あたりのビュー数、平均訪問時間はこのサーバー側で計算されるため、どのレスポンスもそのまま読める形になっています。

• 部分的な失敗。 umami_traffic_reportは内訳を並列実行し、インスタンスがサポートしていないディメンションを除外します。その際、スキップしたディメンションの名前を挙げることで、レポート全体を失敗させません。ディメンションの対応状況はUmamiのバージョンによって異なるため、これは重要です。

• 破壊的操作はオプトインであり、二重確認はありません。 umami_reset_website、umami_delete_website、umami_delete_user、umami_remove_team_user、umami_delete_teamはすべて、リテラルconfirm: trueを引数として必須とし、それ以外では失敗します。独立した「本当に実行しますか？」のやりとりはありません。ツール呼び出し自体が確認であるため、エージェント（または人間）は、意図して実行する場合にのみconfirm: trueを渡すべきです。

• umami_onboard_clientはベストエフォートであり、トランザクショナルではありません。 UmamiのAPIには複数ステップのトランザクション機能はありません。チームの作成に成功してもWebサイトのステップが失敗した場合、チームは残されたままになり、エラーメッセージにはその旨と次に確認すべきことが明示されます。静かにロールバックしたり、部分的な状態を隠したりはしません。

• エスケープハッチ。 umami_api_getは意図的にGET専用で、上記の管理ツールとは分離されています。何も作成・変更・リセット・削除できません。

• レスポンスサイズ。 レスポンスは25,000文字に制限され、limit、offset、またはより狭い範囲を指し示すメッセージが返されます。

テスト

npm test

test/smoke.mjsは、ダミーのUmami APIを立ち上げ、実際のMCPクライアントをstdioで接続し、アナリティクスツールとそのエラーパスを実行します。test/auth.mjsは、セルフホストのログイン交換と、キャッシュ済みベアラートークンが失効したときに発火するトークン更新をカバーします。test/admin.mjsは、Webサイト／ユーザー／チームのCRUD、チームメンバーシップ、複合オンボーディングツールをカバーし、すべての破壊的ツールがconfirm=trueなしでは実行を拒否することを確認します。

検証対象

Umami v3 APIリファレンス（2026年8月時点）: /websites, /websites/:id, /websites/:id/stats, /pageviews, /metrics, /metrics/expanded, /events/series, /active, /daterange, /sessions, /sessions/:id, /sessions/:id/activity, /websites/:id/reset, /users, /admin/users, /users/:id, /users/:id/websites, /users/:id/teams, /teams, /teams/join, /teams/:id, /teams/:id/users, /teams/:id/users/:userId, /teams/:id/websites。クラウドへのリクエストは、ベアラートークンを用いてhttps://api.umami.is/v1へ送信されます。セルフホストへのリクエストは{base}/apiへ送信されます。ユーザーおよびチーム管理エンドポイントは、セルフホストインスタンスにのみ存在します。

ライセンス

MIT