Umami MCP Server

Umami Analytics 用の Model Context Protocol サーバーです。 Claude、Cursor、または任意の MCP クライアントにトラフィックについて質問したり、ウェブサイトの作成・管理を任せたりできます。認証情報は自分のマシン上に留まります。

"Which pages drove the most visitors last month, and where did that traffic come from?"
"Build a funnel from /pricing to /signup to /welcome for the last 30 days."
"Add analytics for my new site blog.example.com and give me the tracking snippet."

なぜこれを作ったのか

Umami には公式の MCP サーバーがありません。コミュニティ製のものはいくつか存在し、広範な API カバレッジだけが必要なら、まず 0xtlt/umami-mcp を検討すべきです。これは当サーバーより多くの API をラップしています。古いサーバーのいくつか (jakeyShakey、 mikusnuz、 mittwald、 Macawls) は v2 API 向けに書かれており、v3 ではエイリアスなしで名前が変更されたため、現代のインスタンスでは動作しません。

このサーバーは、他のサーバーがやらない2つのことを目的としています。

1. 完全かつ検証済みの v3 レポートカバレッジ。 7種類すべての v3 レポートタイプ（ファネル、リテンション、ジャーニー、ゴール、収益、アトリビューション、UTM）を、実稼働中の Umami 3.3.1 インスタンスに対して実行して検証しました。レポートのエンベロープは間違えやすい部分です。日付は filters ではなく parameters に ISO-8601 文字列として入れます。また、API の他の部分で使うエポックミリ秒ではありません。アトリビューションは、推測したくなる camelCase 表記ではなく、first-click / last-click を取ります。

2. ブール値ではなくケイパビリティモデル。 以下を参照してください。

Related MCP server: Umami MCP Server

セキュリティモデル

アナリティクス MCP サーバーは、記録したすべての訪問者セッションを読める認証情報を保持します。そして、許可すれば、そのすべてを削除することもできます。設計はその前提に従っています。

認証情報が環境の外に出ることはありません。 設定はプロセス環境からのみ読み取られます。テレメトリも、ホームへの連絡も、ホスト型リレーもありません。このサーバーが接続する唯一のホストは、設定した UMAMI_URL だけです。セルフホストする場合、アナリティクスに関する情報が第三者（このソフトウェアの作者を含む）に届くことは一切ありません。

インスタンスを向けるホスト型エンドポイントを提供する Umami MCP には注意してください。 セルフホストの Umami には API キーがないため、「便利な」ホスティングとは、管理者パスワードを他人のサーバーに送ることを意味します。

デフォルトで最小権限。 サーバーは read モードで起動します。権限の拡大は意図的な行為です。

保留されたツールは一切登録されません。そのため、モデルのツールリストに表示されることはありません。これが READONLY=true フラグとの違いです。宣伝されなかったツールは、たとえば自分のアナリティクスデータ内のリファラ文字列やページタイトルに隠されたプロンプトインジェクションの指示によって呼び出されることはありません。ツールが存在しないため、忘れたりバイパスしたりするランタイムチェックもありません。

破壊的操作には、現実と照合される型付き確認が必要です。 umami_delete_website は confirmDomain 引数を受け取り、実在するレコードを取得して、一致しない限り拒否します。間違ったウェブサイト UUID に手を伸ばしたモデルは、消去されたデータセットではなくエラーを受け取ります。

認証情報はクライアント設定に残りません。 ~/.claude.json や mcp.json にパスワードを埋め込む代わりに、サーバーは ~/.config/umami-mcp/env にある自分が管理するファイルから読み取り、そのファイルが他のユーザーに読み取り可能な場合は警告します。認証情報を参照してください。

シークレットは出力から削除されます。 MCP の出力はモデルに流れ、多くの場合チャットのトランスクリプトにも流れますが、これは取り消せません。パスワード、ベアラートークン、JWT は、プロセスから出る前にすべてのエラーとレスポンスから編集されます。

認証情報をネットワーク経由で漏らすことを拒否します。 リモートホストへの平文 HTTP は起動時に拒否されます。許可されるのはローカル開発用の localhost のみです。

インストール

実行方法は3つあります。セルフホスティングがデフォルトであり推奨です。ホスト型インスタンスは、何もクローンせずに2分で試せるように存在しています。

セルフホストして Claude web で使いたい場合は、自分のドメインの背後で UMAMI_MCP_OAUTH=true を指定して実行してください。そうすれば、あなたのデータが他人のインフラに触れることはありません。

1. ホスト型インスタンスを使う（インストール不要）

Claude にカスタムコネクタを追加して、次の場所を指定します:

https://umami-mcp.asif.dev/mcp

同意画面で自分の Umami URL とログイン情報を求められます。認証情報の扱いについては Claude web、Cowork、Claude Code on web を参照してください。

2. ソースから

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
npm install && npm run build

次に 認証情報 を設定し、クライアントに登録します:

claude mcp add umami --scope user -- node "$PWD/dist/index.js"

Node 20 以降が必要です。

3. Docker

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
cp .env.example .env    # then edit .env
docker compose up -d

npm: まだ公開されていません。公開され次第、npx -y @asif2bd/umami-mcp が上記のクローン＆ビルド手順に取って代わります。それまではソースまたは Docker を使用してください。

認証情報

セルフホストの Umami には API キーがないため、このサーバーが保持する認証情報は実際のアカウントパスワードです。MCP クライアントは通常、それを設定 JSON（~/.claude.json、mcp.json など）に埋め込むことを要求しますが、これらのファイルは広く読み取り可能で、issue や画面共有に貼り付けられ、一部のクライアントではマシン間で同期されます。

そこで、このサーバーは自分が管理するファイルから認証情報を読み取ります。一度作成するだけです:

mkdir -p ~/.config/umami-mcp
cat > ~/.config/umami-mcp/env <<'EOF'
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=mcp-bot
UMAMI_PASSWORD=your-password
UMAMI_MCP_MODE=read
EOF
chmod 600 ~/.config/umami-mcp/env

サーバーは自動的に読み込みます。ファイルが他のユーザーに読み取り可能な場合、起動時に警告します。

検索順序 — 最初に見つかったファイルが優先され、実際の環境変数は常にファイルより優先されます。必要に応じてクライアント設定から設定を渡すこともできます。

1. $UMAMI_MCP_ENV_FILE（設定されている場合）

2. ~/.config/umami-mcp/env（または $XDG_CONFIG_HOME/umami-mcp/env）

3. 作業ディレクトリの ./.env

クライアントを接続する

Claude Code

上記の認証情報ファイルがあれば、登録にシークレットは一切含まれません:

claude mcp add umami --scope user -- node ~/umami-mcp/dist/index.js

チェックアウトしたディレクトリの絶対パスを使用してください。Node が nvm 配下にある場合は、MCP クライアントはシェルプロファイルを読み込まないため、インタープリタのフルパスも指定してください:

claude mcp add umami --scope user -- ~/.nvm/versions/node/v22.22.0/bin/node ~/umami-mcp/dist/index.js

Claude Desktop / Cursor / VS Code

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"]
    }
  }
}

すべてを1か所にまとめたい場合は、環境変数も引き続き機能し、ファイルより優先されます:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-bot",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

動作確認

クライアントに umami_whoami を実行させてください。インスタンス、アカウント、権限モードが報告されます。接続を確認し、サーバーがどの程度の操作を許可されているかを確認する最も速い方法です:

{
  "instance": "https://analytics.example.com",
  "authenticatedAs": "mcp-bot",
  "role": "admin",
  "serverMode": "read",
  "destructiveOperations": "disabled"
}

次に、「Umami のウェブサイトを一覧表示して」 や 「先週のトップページは？」 を試してください。

Claude web、Cowork、Claude Code on web

これらのクライアントはローカルプロセスを起動できないため、公開 HTTPS MCP サーバーが必要です。また、コネクタ UI はOAuth のみを受け付け、静的ベアラートークンやカスタムヘッダーのフィールドはありません。

当然の方法でホストする場合、つまり1組の Umami 認証情報を埋め込み、認証なしにすると、その URL はその Umami へのオープンプロキシになります。そこで、このサーバーは OAuth を採用し、しかも認証情報ストアにならないように実装しています。

ホスト型インスタンスを使う

Claude にカスタムコネクタを追加し、この URL を指定します:

https://umami-mcp.asif.dev/mcp

Claude が自分自身を登録し、同意画面に誘導し、あなた自身の Umami URL、ユーザー名、パスワードを求めます。ホストの他のユーザーと共有されるものはありません。

自分でホストする

UMAMI_MCP_OAUTH=true
UMAMI_MCP_TRANSPORT=http
UMAMI_MCP_ISSUER=https://mcp.example.com      # public HTTPS URL of this server
UMAMI_MCP_TOKEN_KEY=<32 random bytes>          # keep stable; see below
UMAMI_MCP_TOKEN_TTL=2592000                    # 30 days

キーを一度生成して保管します:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

UMAMI_URL も設定すると、ユーザーが自由に選択する代わりに、すべてのユーザーを1つのインスタンスに固定できます。

認証情報の扱い方

同意画面は、ユーザーが指定した Umami インスタンスに対して認証情報を検証し、AES-256-GCM でアクセストークンに封印します。サーバーはセッションテーブルを保持せず、認証情報も保存しません。各リクエストはトークンを復号し、その1人のユーザーにスコープされた MCP サーバーを構築し、呼び出しを処理して破棄します。

正直なトレードオフ: UMAMI_MCP_TOKEN_KEY を保持する者は、取得した任意のトークンを復号できます。デプロイメントで最も機密性の高い値として扱ってください。ローテーションすると発行済みのすべてのトークンが無効になります。これが意図された爆発半径の制御です。

破壊的ツールは、ユーザーがどの権限を選択しても、OAuth 経由では決して公開されません。型付き確認ガードは、削除しようとしているものを確認できるローカルオペレーターを前提としており、リモートの呼び出し元にはそれを表示できません。

プレーンな HTTP サービスとして実行する

UMAMI_MCP_OAUTH なしで UMAMI_MCP_TRANSPORT=http を設定すると、/mcp にシングルテナントのエンドポイントと /health が提供されます。

このモードでは、サーバー自体に認証はありません。 ポートに到達できる人は誰でも、あなたの Umami 認証情報を使用できます。ループバックに保持し、トンネルで接続してください:

ssh -N -L 3334:127.0.0.1:3334 you@your-server
claude mcp add --transport http umami http://127.0.0.1:3334/mcp

サーバーは、ループバック以外にバインドされている場合、起動時に警告します。

ツール

時間範囲

すべてのアナリティクスツールは、エポックミリ秒の代わりに period の省略形 -- 24h、7d、30d、12m、today、yesterday -- を受け付けます。モデルは「過去 30 日間」のような表現は確実に処理できますが、タイムスタンプの算術は信頼性が低く、計算を誤ったエポック値はエラーを出さずに間違った期間のデータを返します。明示的な startAt/endAt（エポックミリ秒）は引き続き機能し、優先されます。

設定

すべてのオプションは .env.example を参照してください。基本事項:

推奨セットアップ

管理者ログインを使い回すのではなく、MCP サーバー専用の Umami アカウントを作成し、必要なウェブサイトのみを付与してください。そうすれば、認証情報が漏洩した場合でも、影響範囲は削除可能なボットアカウント 1 つに留まります -- 管理者アカウントではありません。

互換性

Umami 3.3.1（セルフホスト、PostgreSQL）で検証済みです。Umami Cloud は UMAMI_API_KEY で動作します。Umami v2 はサポートされていません: 上記のリネームされたメトリクスタイプにより、v2 と v3 では異なるクライアントが必要であり、このサーバーは v3 を対象としています。

開発

npm install
npm run build
npm test          # unit tests, no network required

test/e2e.mjs と test/write-e2e.mjs は、ビルドされたサーバーを実際の MCP クライアント経由でライブインスタンスに対して駆動します。書き込みテストは .invalid ドメインに使い捨てのウェブサイトを作成し、再度削除します。本番以外のインスタンスを指定してください。

貢献

Issue とプルリクエストを歓迎します。Umami v3 は約 127 の API ルートを公開しており、このサーバーは最も有用なものをカバーしています -- セッションリプレイ、ヒートマップ、ピクセル、リンクトラッキング、ボード、セグメントはまだマッピングされていません。ツールを追加する場合は、ティアと destructive フラグを正直に保ってください。セキュリティモデル全体がこれらに依存しているためです。

Umami チームがこれを採用、フォーク、またはアップストリームに取り込みたい場合は、Issue を開いてください -- それがこのプロジェクトが作られた目的です。

ライセンス

MIT © M Asif Rahman