ObsidianCorps Umami Analytics

ObsidianCorps Umami MCP

自分でホストする Umami アナリティクスについて質問し、データを別のアナリティクス SaaS に送信せずに利用できます。

Umami Cloud およびセルフホスト型の Umami Analytics 向けに、安全でモデルに使いやすい Model Context Protocol サーバーです。Umami v3.3.1 と 2026-07-28 MCP protocol を対象としながら、2025 年代の MCP クライアントとの互換性も維持しています。

インストール

要件：Node.js 20 以降と、設定済みの 認証モード 1 つ。

npx -y @obsidiancorps/umami-mcp

次のように質問してみてください。

• 「先月と比べてウェブサイトのトラフィックを比較してください。」
• 「最も多くのコンバージョンを生み出した参照元はどれですか？」
• 「Web Vitals の低いページを見つけてください。」

エージェントスキル

このリポジトリには Umami Analytics スキル も含まれています。 MCP サーバーは Umami へのアクセスを提供し、スキルはそれらのツールを使ったトラフィック比較、 コンバージョン分析、収益、パフォーマンス調査をエージェントに案内します。 これは Agent Skills format に準拠しています。

MCP Market の GitHub からインポート では、スキルフォルダーの URL を使用してください。

https://github.com/ObsidianCorps/umami-mcp/tree/main/skills/umami-analytics

URL は SKILL.md を含むフォルダーを指している必要があります。公開リポジトリの場合は、 公開リポジトリ を選択してください。マーケットプレイスからインポートできるようにするには、 フォルダーを main にプッシュしておく必要があります。

手動でインストールするには、skills/umami-analytics をエージェントのスキルディレクトリにコピーします （たとえば、プロジェクト内の .claude/skills/umami-analytics）。MCP サーバー は別途設定して 認証してください。スキルをインポートしても、サーバーはインストールされず、 アナリティクスへのアクセス権も付与されません。

この実装の特長

• Umami v3 の最新機能を網羅：収益 API、セッションリプレイ、ヒートマップ、イベント／セッションプロパティのピボットと型付き系列、セグメント、コホート、ボード、リンク、ピクセル、Web Vitals レポート、および従来のアナリティクス API。
• コンパクトなモデル向けインターフェース：17 個の読み取りツールで、数十個のよく似たエンドポイントツールを並べるのではなく、分析ワークフローに沿って API を整理します。
• モデルに使いやすい入力：ウェブサイト名／ドメインは自動で解決され、アクセス可能なウェブサイトが 1 つの場合は自動選択されます。また、日付範囲にはプリセットまたは正確な ISO／epoch タイムスタンプを指定できます。
• 構造化された MCP 結果：すべてのツールが出力スキーマを公開し、structuredContent と読みやすい JSON を返します。
• 安全なデフォルト設定：デフォルトでは変更操作がなく、破壊的なツールには追加のオプトインと、対象を指定した正確な確認文字列が必要です。
• 2 つの最新トランスポート：ローカル stdio とステートレスな Streamable HTTP。従来の HTTP+SSE は意図的に引き継いでいません。
• 多層防御：レスポンスのバイト数制限、リクエストタイムアウト、HTTPS の強制、トークンの更新、DNS リバインディング保護、厳密なオリジンチェック、定時間の MCP ベアラーチェック。
• Cloud とセルフホスト環境の認証：Umami Cloud API キー、事前発行されたセルフホストトークン、または遅延実行されるユーザー名／パスワード認証（Umami v3.3 以降の二要素認証を含む）。401 の後は 1 回だけ再認証します。

設定

ソースから

要件：Node.js 20 以降。

npm install
npm run build
UMAMI_API_KEY=your-key node dist/cli.js

MCP クライアントの設定例：

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@obsidiancorps/umami-mcp"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_DEFAULT_WEBSITE_ID": "optional-website-uuid"
      }
    }
  }
}

ソースをチェックアウトした場合は、コマンドを node に、引数を dist/cli.js の絶対パスに置き換えてください。

認証

次のモードから必ず1つだけ選択してください。

モード	変数	API ベース URL
Umami Cloud	UMAMI_API_KEY	既定値は https://api.umami.is/v1 です
セルフホストのトークン	UMAMI_BASE_URL、UMAMI_TOKEN	ルート URL に /api が追加されます
セルフホストのログイン	UMAMI_BASE_URL、UMAMI_USERNAME、UMAMI_PASSWORD	ルート URL に /api が追加されます
セルフホストのログイン＋2FA	ログイン用の変数と UMAMI_TWO_FACTOR_SECRET	ルート URL に /api が追加されます
1回限りの2FAログイン	ログイン用の変数と現在有効な6桁の UMAMI_TWO_FACTOR_CODE	ルート URL に /api が追加されます

UMAMI_TWO_FACTOR_SECRET は、認証アプリの登録時に表示される Base32 形式のセットアップシードです。MCP は必要なときに6桁の SHA-1 TOTP を生成し、ログに記録したり返却したりすることはありません。パスワードと TOTP シードを一緒に保存すると、要素間の分離が失われるため、最小限の権限を持つ専用の Umami アカウントを使用し、その環境を保護してください。事前に発行した UMAMI_TOKEN を使えば、どちらの認証情報も保持せずに済みます。

UMAMI_TWO_FACTOR_CODE は1回限りの代替手段であり、すぐに期限切れになるため、通常の MCP 起動には適していません。2要素認証の変数は1つだけ設定してください。

ローカル以外の Umami URL で HTTP を使用することは拒否されます。明示的に信頼されたプライベートネットワーク内でのみ、UMAMI_ALLOW_INSECURE_HTTP=true を設定してください。

ツール

デフォルトの読み取り専用ツールセットは次のとおりです。

ツール	目的
umami_check_connection	認証を確認し、現在のアカウントを調べます
umami_list_websites、umami_get_website	サイトを見つけて調べます
umami_get_overview、umami_get_metrics	KPI、時系列データ、ランキング形式のディメンションを集計します
umami_get_realtime	現在の30分間のアクティビティウィンドウを調べます
umami_list_sessions、umami_inspect_session	セッション、アクティビティ、プロパティ、リプレイのメタデータを閲覧します
umami_query_session_data	セッションのプロパティ、ピボット、統計、週ごとのトラフィック、型付き時系列データをクエリします
umami_list_events、umami_query_event_data	イベント、比較統計、時系列データ、プロパティ、値、ピボットを閲覧します
umami_get_revenue	収益の統計、グラフ、ディメンション、セッションを取得します
umami_list_replays	リプレイを一覧表示するか、リプレイのイベントストリームを取得します
umami_run_report、umami_list_reports	ファネル、ジャーニー、目標、リテンション、アトリビューション、UTM、収益、パフォーマンス、内訳、ヒートマップのレポートを実行または検索します
umami_list_segments	セグメントとコホートを見つけます
umami_list_assets	ボード、トラッキングリンク、ピクセルを見つけます

リソースでは、umami://capabilities と最新の umami://websites リストを公開します。再利用可能なプロンプトでは、アナリティクスのレビュー、コンバージョンのレビュー、リアルタイムのトリアージを行えます。

期間

ほとんどの分析ツールでは、次のいずれかを指定できます。

• period：last_24_hours、last_7_days、last_30_days、last_90_days、today、yesterday、this_week、last_week、this_month、last_month；または
• startAt と endAt の両方を、エポックミリ秒またはオフセット付きの ISO 8601 タイムスタンプで指定します。

カレンダー期間では、指定された IANA timezone が適用されます。ローリング期間では、午前0時に丸めず、直近のデータが保持されます。

変更操作と破壊的な操作

デフォルトでは、変更操作を行うツールは登録されていません。

UMAMI_ENABLE_WRITE_TOOLS=true

これにより、ウェブサイト、セグメント、レポート、ボード／リンク／ピクセルの作成・更新や、アナリティクスイベントの送信を行うツールが追加されます。恒久的なリセット／削除操作も公開するには、次を実行します。

UMAMI_ENABLE_WRITE_TOOLS=true
UMAMI_ENABLE_DESTRUCTIVE_TOOLS=true

破壊的な呼び出しには、RESET <website-id> や DELETE reports <report-id> などの確認文字列が必要です。MCP アノテーションでもこれらのツールは破壊的な操作として識別され、対応するホストで承認を必須にできます。

Streamable HTTP

ループバックの例：

MCP_TRANSPORT=http MCP_BEARER_TOKEN=replace-me npm start
# MCP:    http://127.0.0.1:3000/mcp
# Health: http://127.0.0.1:3000/health

コンテナーまたはループバック以外のアドレスにバインドする場合は、MCP_BEARER_TOKEN と MCP_ALLOWED_HOSTS の両方が必要です：

docker build -t umami-mcp .
docker run --rm -p 3000:3000 \
  -e UMAMI_API_KEY=your-key \
  -e MCP_BEARER_TOKEN=long-random-secret \
  -e MCP_ALLOWED_HOSTS=mcp.example.com \
  umami-mcp

ブラウザベースの MCP クライアントが接続する場合は、MCP_ALLOWED_ORIGINS に正確なブラウザーオリジンをコンマ区切りのリストで設定します。Origin ヘッダーのないリクエストは、引き続きネイティブクライアントで有効です。TLS は信頼できるリバースプロキシで終端してください。組み込みの静的ベアラートークンによるゲートは、その境界の内側で使用するものであり、一般公開のマルチユーザーサービスで OAuth の代わりとなるものではありません。

設定リファレンス

変数	デフォルト	説明
UMAMI_BASE_URL	API キー認証用のクラウド API	Umami のルート URL または完全な API ベース URL
UMAMI_DEFAULT_WEBSITE_ID	—	ほとんどの呼び出しでサイトの解決を省略できます
UMAMI_TIMEOUT_MS	15000	上流リクエストのタイムアウト。100～120000 ms
UMAMI_MAX_RESPONSE_BYTES	512000	上流レスポンスの最大サイズ。1 KB～10 MB
UMAMI_ENABLE_WRITE_TOOLS	false	非破壊的な変更ツールを登録します
UMAMI_ENABLE_DESTRUCTIVE_TOOLS	false	リセット／削除ツールを登録します。書き込みツールが必要です
MCP_TRANSPORT	stdio	stdio、http、またはstreamable-http
MCP_HOST	127.0.0.1	HTTP のバインドアドレス
MCP_PORT	3000	HTTP ポート
MCP_BEARER_TOKEN	—	HTTP MCP エンドポイントを保護します
MCP_ALLOWED_HOSTS	—	ループバック以外の HTTP 用ホスト名のコンマ区切りリスト
MCP_ALLOWED_ORIGINS	—	正確なブラウザーオリジンのコンマ区切りリスト

開発

npm install
npm test
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run check

テストでは、実際のインメモリ、stdio、および Streamable HTTP MCP クライアントを介してサーバーを実行します。変更を提出する前に、CONTRIBUTING.md と SECURITY.md を確認してください。

互換性の基準

• Umami：v3.3.1。文書化されたルートを公開する v3 後期リリースとの互換性が想定されています。
• MCP SDK：TypeScript SDK v2.0.0。
• MCP プロトコル：2026-07-28、および2025年当時のクライアント向けの SDK のステートレス互換性パス。
• Node.js：20、22、24。

Umami は、それぞれの所有者の商標です。この独立した統合は、Umami Software と提携しておらず、同社から承認も受けていません。

ライセンス

Apache-2.0。LICENSE を参照してください。