umami-mcp

Umami MCP サーバー

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 3.3.1インスタンス上で、読み取り専用のサービスアカウントから参照しています。そのため件数は少なく、意味のあるものではありませんが、いずれも実際に収集され、実際にクエリされています。vhs demo/demo.tapeで再生成できます。}

このサーバーがある理由

Umamiには公式MCPサーバーが標準搭載されるようになりました（v3.4.0以降、MCP_ENABLED=1、エンドポイントは/mcp）。読み取り専用の分析機能だけが必要な場合は、こちらをお使いください。Umami内で動作するため、追加のデプロイは不要です。Umamiのドキュメントをご覧ください。

このサーバーは、公式サーバーが意図的に対象外としている機能を提供します。

	公式（/mcp）	umami-mcp
分析とレポートの読み取り	対応	対応
ウェブサイト、チーム、トラッキングスニペットの作成と更新	—	writeモード
ユーザー管理	—	adminモード
ウェブサイトの削除／データのリセット	—	オプトインのみ
Umami 3.4より前のバージョン	—	3.x
サインイン	APIキー	APIキー、パスワード、またはOAuth（マルチテナント）

コミュニティ製のサーバーもいくつかあります。幅広いAPIカバレッジが必要なだけなら、まず0xtlt/umami-mcpをご覧ください。このサーバーより多くのAPIをラップしています。古いサーバーの一部（ jakeyShakey、 mikusnuz、 mittwald、 Macawls）はv2 API向けに作られており、現行インスタンスでは動作しません。v3では別名を設けずに名前が変更されたためです。

	Umami v2	Umami v3
人気ページ	/metrics?type=url	/metrics?type=path
ホスト名	/metrics?type=host	/metrics?type=hostname
UTMデータ	/metrics?type=utm_source	POST /api/reports/utm
ファネル、リテンション、ジャーニー、アトリビューション、収益	—	POST /api/reports/*

このサーバーには、ほかのサーバーにはない2つの機能があります。

1. 完全かつ検証済みのv3レポート対応。 v3の7種類すべてのレポート（ファネル、リテンション、ジャーニー、ゴール、収益、アトリビューション、UTM）を、稼働中のUmami 3.3.1インスタンスで実際に試しました。レポートのエンベロープは間違えやすいものです。日付はfiltersではなく、またAPIのほかの部分で使われるエポックミリ秒でもなく、ISO-8601形式の文字列としてparametersに指定します。アトリビューションでは、推測しがちなキャメルケース表記ではなく、first-click／last-clickを指定します。

2. ブール値ではなく、機能に基づく権限モデル。 詳細は以下をご覧ください。

セキュリティモデル

分析 MCP サーバーには、これまでに記録したすべての訪問者セッションを読み取ることができ、許可すればすべて削除することもできる認証情報が保持されます。設計はこの点を踏まえています。

認証情報が環境の外に出ることはありません。 設定はプロセス環境からのみ読み取られます。テレメトリも、外部への通信も、ホスト型リレーもありません。このサーバーが接続するのは、設定した UMAMI_URL だけです。セルフホストすれば、このソフトウェアの作者を含め、第三者に分析データが送られることはありません。

インスタンスの接続先としてホスト型エンドポイントを案内する Umami MCP には注意してください。Umami 3.4 より前は、セルフホスト型インスタンスに API キーがなかったため、「便利な」ホスティングを使うには、誰かのサーバーに管理者パスワードを送る必要がありました。3.4 以降でそのようなサービスを使う場合は、パスワードではなく、専用アカウントの取り消し可能な API キーを渡してください。

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

モード	追加される機能
read (デフォルト)	分析、レポート、ウェブサイトの一覧表示
write	ウェブサイトとチームの作成・更新
admin	ユーザー管理
+ UMAMI_MCP_ALLOW_DESTRUCTIVE=true	ウェブサイトの削除、データのリセット、ユーザーの削除

無効化されたツールは登録自体されないため、モデルのツール一覧に表示されることもありません。これは READONLY=true フラグとは異なる点です。ツール一覧に一度も表示されていないツールは、たとえばリファラー文字列や、分析データ内のページタイトルに隠された、プロンプトインジェクションされた指示から呼び出すこともできません。忘れたり、回避されたりする可能性のある実行時チェックはありません。ツール自体が存在しないためです。

破壊的な操作には、実際のデータと照合する入力確認が必要です。 umami_delete_website は confirmDomain 引数を受け取り、最新のレコードを取得して、一致しない場合は処理を拒否します。誤ったウェブサイト UUID を指定したモデルには、データセットが消去されるのではなく、エラーが返されます。

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

出力からシークレットを除去します。 MCP の出力はモデルに渡され、チャットの記録にも残ることがよくあります。一度送信した内容は取り消せません。パスワード、ベアラートークン、JWT はすべて、プロセスの外に出る前にエラーとレスポンスからマスキングされます。

通信経由での認証情報漏えいを拒否します。 リモートホストへの平文 HTTP は起動時に拒否されます。ローカル開発の場合に限り、localhost への接続が許可されます。

インストール

実行方法は 3 つあります。デフォルトであり、推奨されるのはセルフホストです。ホスト型インスタンスは、何もクローンせずに 2 分で試せるように用意されています。

	実行場所	認証情報の保存先	最適な用途
ホスト型	asif.dev	トークン内に封印され、保存されません	お試し利用、Claude web と Cowork
ソース	ご利用のマシン	自分だけが読み取れるファイル	Claude Code での日常利用
Docker	ご利用のサーバー	ご利用の .env	チーム、常時稼働

セルフホストして Claude web でも使う場合は、独自ドメインの背後で UMAMI_MCP_OAUTH=true を設定して実行してください。これにより、ご利用のデータが他者のインフラに触れることはありません。

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

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

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 3.4.0 以降では、UMAMI_API_KEY に API キー（Settings → API keys）を設定することをおすすめします。パスワードを変更せずに、API キーだけを失効できるためです。セルフホストのインスタンスには Authorization: Bearer として、Umami Cloud には x-umami-api-key として送信されます。古いインスタンスには API キーがないため、認証情報には 実際のアカウントパスワードを使用します。いずれの場合も、MCP クライアントでは通常、これらを設定 JSON（~/.claude.json、mcp.json など）に埋め込む必要があります。これらのファイルは広く読み取り可能で、課題や画面共有に貼り付けられることもあり、一部のクライアントではマシン間で同期されます。

そこで、このサーバーは認証情報を、ユーザー自身が管理するファイルから読み込みます。一度だけ作成してください。

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 のみで、静的なベアラートークンやカスタムヘッダーを入力する欄はありません。

Umami の認証情報を1組だけ埋め込み、認証なしで一般的な方法でホストすると、その 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'))"

すべてのユーザーを1つのインスタンスに固定し、ユーザーがインスタンスを選べないようにする場合は、UMAMI_URL も設定してください。

認証情報の取り扱い

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

正直なところ、トレードオフがあります。UMAMI_MCP_TOKEN_KEY を保持する人は、取得したあらゆるトークンを復号できます。デプロイ環境で最も機密性の高い値として取り扱ってください。このキーをローテーションすると、発行済みのすべてのトークンが無効になります。これは、影響範囲を制御するための意図された仕組みです。

ユーザーがどの権限を選んでも、破壊的なツールが OAuth 経由で公開されることは 決してありません。入力確認を必要とするガードは、これから削除する対象を確認できるローカルのオペレーターを想定しています。リモートの呼び出し元には、その対象を表示できません。

通常の HTTP サービスとして実行する

単一テナント用の /mcp エンドポイントと /health を有効にするには、UMAMI_MCP_OAUTH を設定せずに UMAMI_MCP_TRANSPORT=http を設定します。

このモードでは、サーバー自体に認証機能はありません。 ポートにアクセスできる人は誰でも、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

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

ツール

ツール	必要な権限	説明
umami_list_websites	read	この Umami インスタンスでトラッキングされているウェブサイトと、その UUID を一覧表示します
umami_get_website	read	UUID を指定して単一のウェブサイトを取得します。ドメイン、所有者、作成日も含まれます。
umami_create_website	write	トラッキング対象として新しいウェブサイトを登録し、その UUID を返します。この UUID は、Umami トラッキングスクリプトの data-website-id 属性に設定する値です。
umami_update_website	write	ウェブサイトの名前、ドメイン、共有スラッグを変更します
umami_reset_website	destructive	ウェブサイト自体は残したまま、収集済みの分析データをすべて完全に削除します
umami_delete_website	destructive	ウェブサイトと、これまでに記録されたすべてのイベントを完全に削除します
umami_get_tracking_snippet	read	指定したウェブサイトのデータをこの Umami インスタンスに送信する、すぐに貼り付けられる HTML スクリプトタグを返します。
umami_get_stats	read	期間を指定したウェブサイトの概要数値：ページビュー、訪問者数、訪問数、直帰数、サイト滞在時間の合計
umami_get_pageviews	read	トラフィックのグラフ化に使える、時間ごとに集計されたページビュー数とセッション数
umami_get_metrics	read	1 つのディメンションの上位項目を訪問者数順に表示します。上位ページ、参照元、国、ブラウザーなどが対象です
umami_get_active_visitors	read	直近数分間にサイトでアクティブだった訪問者数
umami_get_realtime	read	現在のアクティビティのライブスナップショット：国、URL、ブラウザー、デバイスを含む最近のイベントと、国、URL、参照元ごとの集計
umami_get_event_stats	read	期間を指定したカスタムトラッキングイベントの合計：イベント数、ユニークなイベント名の数、訪問者数、訪問数、および前の期間との比較。
umami_list_sessions	read	ブラウザー、OS、デバイス、国、地域を含む、個々の訪問者セッション
umami_get_session_activity	read	1 つの訪問者セッションにおけるページビューとイベントの順序付きシーケンス（サイト内での移動経路）
umami_report_utm	read	UTM パラメーター（source、medium、campaign、term、content）ごとのトラフィック内訳
umami_report_funnel	read	ステップごとのコンバージョンファネル
umami_report_retention	read	コホートリテンション：特定の日に初めて確認された訪問者のうち、その後の日ごとに何人が再訪したか。
umami_report_journey	read	訪問者がサイト内でたどることの多い順序付き経路。各ページのシーケンスと件数を表示します。
umami_report_goal	read	1 つの目標の達成状況：指定したパスまたはカスタムイベントに到達した訪問者数。
umami_report_revenue	read	収益プロパティを含むイベントから得られた収益の推移。国、地域、参照元、チャネルごとに内訳を表示します
umami_report_attribution	read	初回クリックまたは最終クリックのモデルに基づき、参照元、有料広告、UTM パラメーターなどの獲得チャネルにコンバージョンを割り当てます。
umami_list_users	admin	Umami ユーザーアカウントとそのロールを一覧表示します
umami_create_user	admin	Umami ユーザーアカウントを作成します
umami_delete_user	destructive	ユーザーアカウントと、そのユーザーが所有するウェブサイトを完全に削除します
umami_list_teams	read	チームとそのメンバーを一覧表示します。
umami_create_team	write	ユーザー間でウェブサイトを共有できるように、チームを作成します。
umami_whoami	read	この MCP サーバーが設定済みの Umami インスタンスに接続できることを確認し、認証されているアカウントと、サーバーが実行されている権限モードを報告します

期間

すべての分析ツールは、エポックミリ秒の代わりに period の略記（24h、7d、30d、12m、today、 yesterday）を指定できます。モデルは「過去 30 日間」の指定は得意ですが、 タイムスタンプの計算は不得意です。エポック値の計算を誤ると、エラーにならずに 誤った期間のデータが返されます。エポックミリ秒での startAt／endAt の明示指定も引き続き使え、 その場合はこちらが優先されます。

設定

すべてのオプションについては .env.example を参照してください。基本的な設定は次のとおりです。

Variable	Default	Purpose
UMAMI_URL	required	お使いの Umami インスタンス
UMAMI_USERNAME / UMAMI_PASSWORD		セルフホスト版のログイン情報
UMAMI_API_KEY		ログインの代わりに使用する API キー（Umami Cloud、またはセルフホスト版 3.4.0 以降）
UMAMI_MCP_MODE	read	read / write / admin
UMAMI_MCP_ALLOW_DESTRUCTIVE	false	削除とリセットを許可
UMAMI_MCP_TRANSPORT	stdio	stdio または http
UMAMI_MCP_HOST	127.0.0.1	HTTP のバインドアドレス
UMAMI_MCP_PORT	3334	HTTP ポート
UMAMI_MCP_ENV_FILE		認証情報ファイルの明示的なパス

推奨設定

管理者ログインを使い回すのではなく、MCP サーバー専用の Umami アカウントを作成し、必要なウェブサイトだけにアクセスを許可してください。認証情報が漏えいした場合でも、削除できるのはボット用アカウントだけで、管理者アカウントには影響しません。

互換性

Umami 3.3.1 で検証済みで、現在は本番環境（セルフホスト、PostgreSQL）で 3.4.1 に対して稼働しています。 Umami Cloud は UMAMI_API_KEY で動作します。セルフホスト版の 3.4.0 以降もこのキーに対応しています。 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 ドメインを使った使い捨てのウェブサイトを作成して削除します。本番環境以外のインスタンスを指定してください。

貢献

課題の報告やプルリクエストを歓迎します。Umami v3 には約 127 の API ルートがあり、このサーバーはその中でも特に有用なものをカバーしていますが、セッションリプレイ、ヒートマップ、ピクセル、リンクトラッキング、ボード、セグメントはまだマッピングされていません。ツールを追加する場合は、階層と destructive フラグを正確に設定してください。安全性の仕組み全体がこれらに依存しています。

Umami チームでこのプロジェクトの採用、フォーク、または上流への取り込みをご希望の場合は、課題を作成してください。それを目指して構築したプロジェクトです。

ライセンス

MIT © M Asif Rahman