Umami Compass

Umami Compass

Umami Analytics 向けのオープンソース MCP サーバー。クラウド版とセルフホスト版に対応しています。

配布先： umami-compass on npm · io.github.webcredo/umami-compass in the official MCP Registry

Umami Compass は、Umami Analytics 用の安全な読み取り専用Model Context Protocol サーバーです。データベースを公開したり、任意のネットワークリクエストを許可したりすることなく、MCP クライアントに正確な Umami 3.2 アナリティクスを提供します。

バージョン 0.5.1 は現在のソースリリースです。古い Umami バージョンで使用する前に、互換性をご確認ください。

npx の例は安定版 npm リリースチャンネルに従い、MCP プロセスの起動時にチャンネルを確認します。ソースを使って評価する場合は、このリポジトリをクローンし、pnpm install --frozen-lockfile && pnpm build を実行して、MCP コマンドとして node /absolute/path/to/umami-compass/dist/cli.js を使用してください。

このプロジェクトの理由

既存の Umami MCP サーバーはいずれも課題の一部には対応していますが、2026 年 7 月のレビューでは、Umami 3.2 のレスポンス精度、Cloud 認証、安全性の境界、拡張性に不足が見つかりました。Umami Compass は、より高く、テスト可能な品質基準を掲げています。

• 両製品で正しい認証を実現します。Umami Cloud では x-umami-api-key、セルフホストインスタンスでは Bearer 認証／ログイン認証を使用します。
• pageviews と sessions の両方、Core Web Vitals、ファネル、ジャーニー、アトリビューション、リテンション、収益、上限付きヒートマップ、リプレイのメタデータなど、Umami 3.2 に対応したレスポンスを提供します。
• 設計上、読み取り専用です。すべてのツールで MCP の安全性アノテーションを宣言し、作成、更新、削除、生 HTML、任意の URL を扱うツールはありません。
• 多層防御を実施します。アップストリームの接続先を固定し、HTTPS ポリシー、ウェブサイトとチームの許可リスト、範囲・ページ数・レスポンスバイト数の上限、リクエストタイムアウト、キャンセルの伝播、エラーの秘匿化を備えています。
• 意思決定に役立つインサイトを提供します。上限付きのトラフィックとパフォーマンスの全体像、トラフィック変化の根拠、リリース影響の分析、トラッキング健全性の監査、任意の API アクセスを伴わないウェブサイト解決に対応します。
• エージェントに使いやすい出力を実現します。機械可読な structuredContent、共通のステータス／範囲／切り詰め情報のエンベロープ、2 つのリソース、6 つのガイド付きプロンプトを提供します。
• コントリビューターに配慮したアーキテクチャを採用しています。エンドポイントモジュール、依存性を注入できる HTTP、中央集約型のアクセスポリシー、ADR、実際の MCP 統合テストを備えています。

根拠と方法については、日付入りのランドスケープレビューをご覧ください。

クイックスタート

要件：Node.js 22 以降と、可能であれば閲覧のみのアクセス権を持つ Umami アカウント。

以下の例では、自動更新される安定版ランチャーを使用します。

npx --yes --prefer-online umami-compass@latest

@latest は安定版 npm チャンネルを選択し、--prefer-online を指定すると、パッケージのメタデータがキャッシュされていても npm がレジストリを確認します。ただし、該当するリリースがすでに存在する場合、npm はキャッシュ済みパッケージを再利用します。更新は次回の MCP プロセス起動時に反映されます。すでに実行中のローカルサーバーは、自身を置き換えることはできません。

プレビューリリースを利用するには、代わりに umami-compass@next を指定してください。再現性が求められる CI や一元管理された環境では、正確なリリースを固定し、オンライン確認を省略してください。たとえば、npx --yes [email protected] のようにします。無人運用の本番環境では、プレビューチャンネルを絶対に使用しないでください。

Umami Cloud

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "replace-with-your-api-key"
      }
    }
  }
}

UMAMI_API_KEY を設定し、URL を指定しない場合、API ルートはデフォルトで https://api.umami.is/v1 になります。

セルフホスト版 Umami

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-viewer",
        "UMAMI_PASSWORD": "replace-me",
        "UMAMI_WEBSITE_IDS": "6b2c8c10-908c-4a8e-a924-4049eb3bde8c"
      }
    }
  }
}

UMAMI_URL はインスタンスのオリジンであり、末尾に /api が追加されます。リバースプロキシでカスタムの正確な API ルートを公開する場合は、代わりに UMAMI_API_URL を使用してください。

UMAMI_WEBSITE_IDS は任意の安全用許可リストであり、認証情報ではありません。例の UUID を Umami（または list_websites）で取得したウェブサイト ID に置き換え、複数の ID を指定する場合はカンマで区切ってください。または、この変数を削除すると、直接またはチームメンバーシップを通じて表示できるすべてのウェブサイトが検出されます。

UMAMI_TEAM_IDS は、検出およびウェブサイトやレポートへの直接アクセスに対する厳格なチーム境界です。これを設定すると、選択したチーム ID のいずれも持たないユーザー所有のウェブサイトは除外されます。UMAMI_WEBSITE_IDS も設定されている場合、ウェブサイトは両方の許可リストを通過する必要があります。

実際の認証情報をコミットしないでください。可能な場合は、閲覧専用の Umami 専用アカウントと、クライアント／OS のシークレットストアを使用してください。

ツール

最小権限のデフォルト設定では、core,insights が有効になります。これには、8 つの基本的な集計ツールと、意思決定にすぐ活用できる 7 つの集計ワークフローが含まれます。行単位のイベント、セッション、リプレイ、ヒートマップ、その他の機密性の高いモジュールは、引き続きオプトイン方式です。

ツールセット	ツール	デフォルト
core	get_server_info、list_websites、get_website、get_website_stats、get_pageviews、get_metrics、get_active_visitors、get_website_date_range	はい
insights	resolve_website、get_portfolio_overview、analyze_performance_portfolio、explain_traffic_change、compare_traffic_series、analyze_release_impact、tracking_health_check	はい
events	list_events、get_event_stats、get_event_series	いいえ
sessions	list_sessions、get_session_stats、get_session、get_session_activity	いいえ
performance	get_web_vitals、get_performance_breakdown、compare_web_vitals、compare_performance_breakdown、get_performance_cross_tab、get_route_group_performance	いいえ
reports	保存済みレポートとセグメントに加え、目標、ファネル、ジャーニー、リテンション、UTM、アトリビューション、複数フィールドによる内訳レポート	いいえ
revenue	get_revenue_stats、get_revenue_metrics	いいえ
replay	list_replays（メタデータのみ。生の rrweb ペイロードは扱いません）	いいえ
heatmaps	get_heatmap（クリック／スクロールページと、範囲が制限された詳細ポイント）	いいえ

UMAMI_TOOLSETS=all またはカンマ区切りのサブセットを設定してください。デフォルトでは集計ツールが 15 個、all では 42 個有効になります。複数ウェブサイトにまたがるインサイトは 50 サイトに制限され、ウェブサイトの処理ワーカーは同時に 4 つまでです。カーディナリティの高いレポート、パフォーマンス、ヒートマップ、チャネルのファンアウト、アクティビティの結果には、明示的な上限と切り捨てメタデータが含まれます。

get_performance_breakdown では、ページ、ページタイトル、デバイス、ブラウザーのランキングについて、デフォルトで各行に 20 件以上のパフォーマンスイベントが必要です。これは p75 の品質を守るための探索的なガードであり、統計的有意性を示すものではありません。Umami 3.2 はこれらの件数を count(metric) ではなく count(*) で算出するため、Compass は件数をイベント数として表示し、指標固有のサンプルとして表示することはありません。ガードを厳しくするには minimumSampleCount を明示的に設定してください。また、他の条件を満たすすべての行を含めるには、値を 1 に下げてください。

Umami 3.2 では、Compass がサンプル数のガードを適用する前に、ページ、ページタイトル、ブラウザーの候補数が 500 に制限されます。そのため、内訳のレスポンスには、有効な最小値、除外された行数、候補の網羅率、および上流の上限によってフィルタリング後のランキングが不完全になる可能性があるかどうかが示されます。すべての候補を確認でき、いずれもサンプル数が不足している場合、emptyReason は insufficient_sample_size になります。候補数の上限によりその結論を出せない場合、dataStatus は unknown になります。

ツールの成功レスポンスでは、既存の data フィールドを維持したまま、共通の meta エンベロープが追加されます。リクエストに応じて、dataStatus、emptyReason、websiteId、requestedRange、timezone が含まれます。切り捨ては、不完全な主要結果を示す responseTruncated と、上限のあるネストされたセクションを示す sectionsTruncated に分けられます。互換性を保つため、集約フィールドの truncated も引き続き使用できます。

サーバーは、umami://websites とサニタイズ済みの umami://capabilities リソースを公開します。ウェブサイトの検出結果には id、name、domain のみが含まれます。詳細なメタデータが必要な場合は、明示的に get_website をリクエストしてください。get_server_info は、ツールと同じローカルバージョン、有効なツールセット、制限、機能フラグを返します。分析レポート、週次ポートフォリオ概要、トラフィック調査、リリースの影響、トラッキングの健全性、コンバージョン監査を扱うガイド付きプロンプトが用意されています。各プロンプトは、必要なツールセットが有効な場合にのみ登録されます。定期的な概要のスケジュール設定は MCP クライアントの責任です。ローカルの stdio サーバーはバックグラウンドスケジューラーを実行せず、メッセージも送信しません。

パフォーマンス分析と上流の制限

analyze_performance_portfolio は、選択したウェブサイトごとに上限付きのパフォーマンスリクエストを2回、集約トラフィックリクエストを2回実行し、4つのウェブサイトワーカーを使用します。verbosity="compact" はデフォルトの判断サマリーです。standard ではサイトごとの簡潔な行と指標別の詳細分析が追加され、full では正規化されたサイトごとの証拠がすべて返されます。詳細分析の対象ウェブサイトは detailMetric のみで選択されます。ページビューあたりのパフォーマンスイベント数は、1 を超える場合がある比率として返されます。Umami はカバーされたページビューの一意件数を返さないため、実際の収集カバレッジは unknown_upstream のままです。複数ウェブサイトのパーセンタイルは合成できないため、ポートフォリオの p75 値は順位付けされますが、平均は計算されません。

compare_web_vitals は5つのサマリー指標すべてを比較します。compare_performance_breakdown はページ、タイトル、デバイス、ブラウザーの行を対応付け、比較可能な行を先に返します。デフォルトでは minimumSampleCount を下回る行を除外し、上流の上位500件リストが上限に達したため不在が不確かな候補は省略します。includeInsufficient=true を設定すると、有用な比較の後にサンプル数不足の行を追加します。get_performance_cross_tab は、フィルタリングしたファンアウトリクエストを最大10回行って組み合わせを導出し、候補がパフォーマンスイベントとトラフィック指標のどちらに由来するかを報告します。get_route_group_performance は呼び出し元が定義したパス正規表現を受け付け、すべてのルートグループを直接クエリします。ルートグループは重複する場合があり、PostgreSQL と ClickHouse の正規表現方言の詳細は異なる場合があります。

パフォーマンスツールが受け付けるのは、Umami がサポートするデータベースバックエンド間で一貫性のあるページ／タイトルフィルターと永続化された環境フィルターのみです。excludeBounce、リファラー、UTM、ホスト名、クエリ、イベント、タグなど、永続化されないパフォーマンスフィールドは無視せず、エラーとして拒否されます。特に、Umami 3.2 はパフォーマンスレポートで excludeBounce の結合処理をビルドしますが、使用しません。

Umami 3.2 は、指標別のサンプル数やチャートのバケット内の件数を返しません。そのため Compass は、フィールドが存在しないチャートポイントについて count: null を返し、sampleCounts.status="unavailable_upstream" を含め、リクエストされたバケットまたは現在のバケットが不完全な場合は partial: true を設定します。全体の件数には performanceEventCount という名前が付けられます。CLS 以外の指標ですべての値がゼロのパーセンタイル用プレースホルダーは利用不可として扱われます。CLS のゼロ値は有効です。

Umami の集約パフォーマンスレポートでは収集も公開もされないため、LCP の内訳、LCP の要素／リソースの帰属、キャッシュ状態、エッジリージョンは利用不可であることが明示的に報告されます。Compass は、無関係な集約パーセンタイルを差し引いて内訳を推測しません。

フィルター、ダイレクトトラフィック、チャネル、トラフィック品質

プレーン文字列のフィルターは引き続き互換性があります。構造化フィルターでは、equals、not_equals、contains、not_contains、regex、not_regex、is_empty、is_not_emptyを使用できます。等価演算子では、ネイティブのINまたはNOT INの動作に対応する配列を指定できます。

{
  "filters": {
    "referrer": { "operator": "is_empty" },
    "path": { "operator": "not_equals", "value": ["/admin", "/internal"] }
  }
}

互換性のため、{"referrer": ""}を指定すると、参照元ドメインが空の行も抽出されます。これはUmamiのdirectチャネルと常に同じとは限りません。参照元のない訪問でも、キャンペーンパラメーターがあれば、アフィリエイト、メール、有料、または別のチャネルに割り当てられる場合があります。Umamiのチャネル帰属を正確に取得するには、filters.channel: "direct"を使用してください。Compassでは、構造化フィルターと空の参照元フィルターにUmamiの中立的な参照元ドメイン列を使用するため、Umamiの外部参照元に関する動作によって内部トラフィックや参照元のないトラフィックが誤って除外されることはありません。

explain_traffic_change、analyze_release_impact、run_breakdown_reportでは、directを含むfilters.channelを指定できます。また、run_breakdown_reportではchannelをフィールドとして指定できるため、channel × deviceのようなリクエストも機能します。Umami 3.2では、チャネルをフィルターまたは内訳フィールドとしてネイティブに公開していません。Compassは、上限付きの拡張メトリックのファンアウトによってこれらの結果を導出し、候補の網羅率、省略された行数、リクエスト数、打ち切りの有無をdataQualityに報告します。チャネルのクロス集計は、カスタムイベントやfilters.match: "any"と組み合わせることはできません。Umamiでは、必要な候補条件をそのORグループの外側で表現できないためです。Compassは、重複した合計を返すのではなく、これらのリクエストを拒否します。

トラフィック変化、リリース影響、比較系列、内訳の結果では、生成されたように見えるドメイン、非常に高い直帰率、ほぼゼロの訪問時間、最低トラフィック量という組み合わせに基づき、リファラースパム候補を保守的に識別します。trafficSegmentをhumanに設定すると、ネイティブの否定フィルターを使用して、トラフィック結果からこれらの候補のみを除外できます。両方の期間を評価できない場合や、必須の除外条件がfilters.match: "any"によって弱められる場合、このプリセットは安全側に動作して失敗します。検出結果は確定的なボット分類ではなくヒューリスティックであり、根拠としきい値を含みます。Umami 3.2のパフォーマンスイベントには参照元の除外を適用できないため、リリース影響分析では、異なるオーディエンスを黙って比較するのではなく、そのパフォーマンスに関する根拠をscope_mismatchとして示します。

analyze_release_impactは、デフォルトで簡潔なエグゼクティブサマリー、正確な比較期間、推奨する確認事項を返し、内訳のファンアウトを回避します。内訳、トラフィック品質の根拠、Web Vitalの変更の全容を取得するには、detailLevelをfullに設定してください。既知の前後のデプロイをotherReleasesで渡すと、Compassは結果を単一のリリースに起因するものとせず、交絡がある可能性を示せます。Web Vitalのサンプルが不十分な場合、主判定はinsufficient_dataとなり、sampleReadinessにはトラフィックとパフォーマンスの不足状況、推定されるrecheckAt、観測された発生率から実現可能な場合は、同じ期間をより長く取る案が示されます。

compare_traffic_seriesは、DSTの切り替わりを含め、指定されたタイムゾーンの実際のバケットに基づいて、疎な行を補完します。現在の期間と比較期間でローカル時間のバケット数が異なる場合、補正前の系列を返し、alignedChangesAvailable: falseを設定します。また、比較をずらす代わりに、導出されたバケット差分を省略します。

構造化フィルターでは、フィールドごとの長さ制限、条件ごとに最大20値、1リクエストあたり30条件および100値までという制限に加え、シリアライズ後のクエリサイズが16 KiBまでという制限が適用されます。

設定

認証方式は必ず1つだけ選択してください。

認証

• UMAMI_API_KEY — Umami Cloud／クライアントのAPIキーです。x-umami-api-keyとしてのみ送信されます。
• UMAMI_ACCESS_TOKEN — 既存のBearerトークンです。
• UMAMI_USERNAME + UMAMI_PASSWORD — セルフホスト環境向けの遅延ログインです。トークンをキャッシュし、401時に1回更新します。

認証変数にデフォルト値はありません。上記3つの方式から1つだけ設定してください。

エンドポイントとアクセス範囲

• UMAMI_URL — セルフホスト可能なインスタンスのオリジンです。/api が追加されます。API キー認証を使用し、URL が指定されていない場合、デフォルトで Umami Cloud API のルートが使用されます。
• UMAMI_API_URL — 正確な API ルートです。UMAMI_URL の代わりに使用されます。デフォルト値はありません。
• UMAMI_WEBSITE_IDS — カンマ区切りのウェブサイト UUID 許可リストです。デフォルトでは、直接またはチームメンバーシップを通じて表示できるすべてのサイトが対象になります。
• UMAMI_TEAM_IDS — 検出およびウェブサイト／レポートへの直接アクセスに使用する、カンマ区切りの厳密なチーム UUID 許可リストです。最大 25 個の ID を指定できます。設定すると、ユーザー所有のウェブサイトは除外され、両方が設定されている場合は UMAMI_WEBSITE_IDS との共通部分が対象になります。
• UMAMI_TOOLSETS — カンマ区切りのツールセット、または all です。使用できる値は core、insights、events、sessions、performance、reports、revenue、replay、heatmaps です。デフォルトは core,insights です。

安全性の上限

• UMAMI_REQUEST_TIMEOUT_MS — リクエストごとのタイムアウトです。1,000～120,000 ms の範囲で指定できます。デフォルトは 30000 です。
• UMAMI_MAX_RANGE_DAYS — 分析対象期間の最大日数です。1～3,650 日の範囲で指定できます。デフォルトは 366 です。
• UMAMI_MAX_RESPONSE_BYTES — デコード後の上流 JSON 本文の最大サイズです。102,400～52,428,800 バイトの範囲で指定できます。デフォルトは 10485760 です。
• UMAMI_ALLOW_INSECURE_HTTP — true に設定すると、ループバック以外での HTTP を許可します。デフォルトは false です。

デフォルトでは HTTPS が必須です。プレーン HTTP が自動的に許可されるのは、localhost、127.0.0.1、::1 のみです。

クライアントの設定

以下のすべての例では Umami Cloud を使用します。クライアントを起動する環境でシークレットをエクスポートしてください。

export UMAMI_API_KEY="replace-with-your-api-key"

セルフホスト可能な Umami では、UMAMI_API_KEY をセルフホスト可能な Umamiに記載されている変数に置き換えてください。アカウントに該当する Umami セクションの権限があり、オプションのデータサーフェスを使用する場合に限り、UMAMI_TOOLSETS=all を追加してください。

Codex CLI、IDE 拡張機能、ChatGPT デスクトップ

同じホスト上の Codex クライアントと ChatGPT デスクトップは、~/.codex/config.toml を共有します。env_vars を使うと、設定ファイルにシークレットの値を書き込まずに渡せます。

[mcp_servers.umami-compass]
command = "npx"
args = ["--yes", "--prefer-online", "umami-compass@latest"]
env_vars = ["UMAMI_API_KEY"]

codex mcp list または /mcp を実行して確認してください。Codex IDE 拡張機能または ChatGPT デスクトップでは、MCP サーバーを開き、コマンド npx --yes --prefer-online umami-compass@latest を指定して STDIO サーバーを追加し、クライアントを再起動することもできます。公式のCodex と ChatGPT の MCP ガイドを参照してください。

ChatGPT ウェブ版は、ローカルの Codex 設定を読み込みません。現在のパッケージはローカル stdio です。ホスト型プラグインには、将来提供される認証済みリモートトランスポートが必要です。

Claude Code

個人用サーバーをリポジトリの外に置くには、ユーザースコープを使用してください。

claude mcp add --scope user --transport stdio \
  --env UMAMI_API_KEY="$UMAMI_API_KEY" \
  umami-compass -- npx --yes --prefer-online umami-compass@latest

claude mcp list または /mcp で確認してください。チームで安全に共有できる .mcp.json では、Claude Code は ${UMAMI_API_KEY} の展開をサポートしています。実際の値は決してコミットしないでください。公式のClaude Code MCP ガイドを参照してください。

Claude Desktop

Settings → Developer → Edit Config を開きます。macOS ではファイルは ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json です。

{
  "mcpServers": {
    "umami-compass": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "replace-with-your-api-key"
      }
    }
  }
}

このクライアント形式では値が保存されるため、設定ファイルを保護してください。その後、Claude Desktop を完全に終了して再起動します。公式のローカル MCP サーバーガイドを参照してください。

Cursor

非公開のグローバル設定ファイル ~/.cursor/mcp.json に記述するか、実際の認証情報が含まれない場合に限り .cursor/mcp.json に記述してください。

{
  "mcpServers": {
    "umami-compass": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "replace-with-your-api-key"
      }
    }
  }
}

Cursor Settings → MCP でサーバーを有効にしてください。公式のCursor MCP ドキュメントを参照してください。

VS Code / GitHub Copilot

個人用設定には MCP: Open User Configuration を、共有コマンドには .vscode/mcp.json を使用してください。VS Code は mcpServers ではなく servers を使用し、マスクされたシークレットの入力を求めることができます。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "umami-api-key",
      "description": "Umami API key",
      "password": true
    }
  ],
  "servers": {
    "umami-compass": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "${input:umami-api-key}"
      }
    }
  }
}

MCP: List Servers を実行して、起動、確認、またはトラブルシューティングを行ってください。公式のVS Code MCP ガイドを参照してください。

Gemini CLI

ユーザーレベルの ~/.gemini/settings.json（またはプロジェクトの .gemini/settings.json）に追加してください。Gemini は env 内のシェル変数を展開します。

{
  "mcpServers": {
    "umami-compass": {
      "command": "npx",
      "args": ["--yes", "--prefer-online", "umami-compass@latest"],
      "env": {
        "UMAMI_API_KEY": "$UMAMI_API_KEY"
      },
      "trust": false
    }
  }
}

gemini mcp list または /mcp で確認してください。詳しくは公式の Gemini CLI MCP ガイド をご覧ください。

トラブルシューティング

• まず npx --yes --prefer-online umami-compass@latest --version を実行してください。Node.js 22 以降が必要です。
• パッケージの更新後は、クライアントが新しいツール一覧を取得できるよう、MCP サーバーを再起動してください。古い一覧や空の一覧がクライアントに表示される場合は、キャッシュされたツールのクリアも必要なことがあります。
• 401 は認証情報または認証モードが誤っていることを意味します。403 は、Umami アカウントにそのウェブサイトのセクションへのアクセス権がないことを意味する場合があります。
• セルフホスト環境でのローカル開発では、http://localhost:3000 が許可されています。それ以外の平文 HTTP オリジンには、明示的な安全でない接続のオプトインが必要です。
• まずはデフォルトのツールセットを使ってください。必要に応じて performance、reports、revenue、replay、heatmaps を有効にしてください。
• クライアントが行単位のデータを必要とし、Umami の ID にそのデータの公開が許可されている場合にのみ、events または sessions を有効にしてください。

アーキテクチャ

flowchart LR
  Client["MCP client"] -->|stdio / JSON-RPC| Server["MCP server"]
  Server --> Policy["Module + access policy"]
  Policy --> Modules["Core / Events / Sessions / Performance / Reports / Revenue / Replay / Heatmaps"]
  Modules --> API["Typed, fixed-origin Umami client"]
  API -->|"API key / Bearer / lazy login"| Umami["Umami Cloud or self-hosted 3.2+"]

このパッケージは、意図的に stdio を最初に提供します。公開 HTTP トランスポートには OAuth 2.1、テナント分離、レート制限、運用上の脅威モデルが必要です。認証されていないエンドポイントをバインドすると、プロジェクトの安全性が損なわれます。

将来的な管理ツールは想定されていますが、読み取り専用ビルドに誤って混入することはありません。各モジュールは access: "read" | "write" を宣言し、サーバーはデフォルトのポリシーで書き込みモジュールを拒否します。アーキテクチャ と ADR-0001 をご覧ください。

実装済みの機能、意図的に除外した機能、今後の優先事項については、Umami 3.2 API カバレッジマトリックスをご覧ください。

開発

corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm dev

エンドポイントを追加するには、ツールの追加に従ってください。プロジェクトの要件とプルリクエストについては、CONTRIBUTING.mdをご覧ください。

互換性

• Umami 3.2.x を基準実装およびテスト対象としています。
• 古い Umami リリースでも変更されていないエンドポイントは動作する場合がありますが、現時点では保証されません。
• CI では Node.js 22、24、26 をテストしています。
• 2026 年 7 月時点で安定した本番向けバージョンであるため、MCP SDK v1 を使用しています。v2 ブランチはまだプレリリースです。

セキュリティとプライバシー

アナリティクス、セッションのメタデータ、収益、リプレイのメタデータには機密情報が含まれる場合があります。最小権限の認証情報、許可リスト、必要最小限のツールセット、短い期間を使用してください。本番環境で使用する前に SECURITY.md をお読みください。

Umami Compass は独立したコミュニティプロジェクトであり、Umami Software とは関係ありません。

プロジェクトを支援する

Umami Compass は無料のオープンソースです。時間の節約やアナリティクスのワークフロー改善に役立った場合は、Ko-fi でコーヒーをおごってプロジェクトを支援できます。

ライセンス

MIT © 2026 webcredo および Umami Compass コントリビューター。