Umami MCPサーバー

Umamiアナリティクス用の読み取り専用MCPサーバーです。HTTP経由でUmami REST APIと直接通信し、主にセルフホスト環境のUmamiをサポートしますが、Umami CloudのAPIキーでも動作します。

このリポジトリは、上位層のエージェントが毎回Umamiのドキュメントを読み直すことなくアナリティクス情報を取得できるように構築されています。ブラウザ自動化、DOMスクレイピング、書き込み操作は一切行いません。

機能

一般的なUmamiアナリティクスクエリのための読み取り専用MCPツール
2つの認証モード:
- UMAMI_API_KEY
- UMAMI_USERNAME + UMAMI_PASSWORD
メモリ内でのセルフホスト用ベアラトークンキャッシュ
ユーザー名/パスワードモードでの自動再ログインおよび401発生時の1回のリトライ
ISO形式の時刻文字列とミリ秒単位のタイムスタンプの両方に対応
統計、ページビュー、内訳、イベントシリーズ全体で共有されるフィルタ処理
小規模で保守性の高いモジュールによる厳格なTypeScript実装
明確な構造化ツール出力と明示的なエラーカテゴリ

要件

Node.js >= 20
pnpm >= 10

インストール

npmからインストール:

npm install -g umami-analytics-mcp

またはインストールせずに実行:

npx -y umami-analytics-mcp

このリポジトリでローカル開発を行う場合:

pnpm install

設定

.env.exampleから.envファイルを作成します。

cp .env.example .env

以下の認証オプションのいずれかを入力してください:

APIキーモード

UMAMI_API_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

セルフホストのユーザー名/パスワードモード

UMAMI_API_URL=https://umami.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

注意:

UMAMI_API_URLは、サイトのオリジンだけでなく、APIのベースURLを指定する必要があります。
UMAMI_API_KEYとユーザー名/パスワードの両方が設定されている場合、UMAMI_API_KEYが優先されます。
UMAMI_DEFAULT_TIMEZONEは、ツールがタイムゾーンをサポートしており、かつ指定を省略した場合に使用されます。

ローカルでの実行

開発モード:

pnpm dev

ビルドして実行:

pnpm build
pnpm start

サーバーはMCP stdioトランスポートを使用するため、クライアントが切断されるまでstdin/stdoutに接続されたままになります。

npmからインストールした場合、同等のコマンドは以下の通りです:

umami-analytics-mcp

テスト

pnpm test
pnpm build

デフォルトではスキップされる、実際のAPIを使用した統合テストテンプレートもあります:

UMAMI_INTEGRATION_TEST=1 pnpm test:integration

MCP Inspector

最初にビルドします:

pnpm build

次に、ビルドされたサーバーに対して公式のMCP Inspectorを起動します:

npx @modelcontextprotocol/inspector node dist/cli.js

開発中のホットリロードには、以下も有効です:

npx @modelcontextprotocol/inspector pnpm dev

公開されたパッケージパスをテストしたい場合は、以下を使用してください:

npx @modelcontextprotocol/inspector npx -y umami-analytics-mcp

Inspectorプロセスで同じUmami環境変数が利用可能であることを確認してください。

Inspectorでの推奨スモークテスト:

umami_ping
umami_list_websites
umami_get_stats
umami_get_breakdown

ツール

`umami_ping`

設定と認証を検証します。

例:

{}

`umami_list_websites`

アクセス可能なウェブサイトを一覧表示します。

例:

{}

`umami_find_website`

ウェブサイト名またはドメインによるあいまい検索を行います。

例:

{
  "query": "example.com"
}

`umami_get_stats`

ウェブサイトと期間の統計サマリーを取得します。

例:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-23T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "filters": {
    "path": "/pricing"
  }
}

`umami_get_pageviews`

時系列のページビューとセッションを取得します。

例:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day",
  "compare": "prev",
  "filters": {
    "path": "/blog"
  }
}

`umami_get_breakdown`

トップページ、リファラー、国、ブラウザ、デバイスなどの内訳行を取得します。

例:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "type": "path",
  "limit": 10,
  "expanded": false
}

`umami_get_active`

現在のアクティブな訪問者数を返します。

例:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab"
}

`umami_get_events_series`

カスタムイベントの時系列カウントを返します。

例:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day"
}

共有フィルタ

これらのツールは、同じfiltersオブジェクトをサポートしています:

path
referrer
title
query
browser
os
device
country
region
city
hostname

エラーハンドリング

ツールのエラーは、以下のカテゴリを持つ構造化されたMCPツール結果として返されます:

config_missing
auth_failed
website_not_found
umami_http_error
network_timeout
network_error
invalid_input

任意のStdio MCPクライアントへのマウント

StdioベースのMCPクライアントであれば、以下の設定でこのサーバーを実行できます:

command: npx
args: ["-y", "umami-analytics-mcp"]
env: Umamiの環境変数

mcpServersオブジェクトを使用するクライアント向けのJSONスニペット例:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_URL": "https://umami.example.com/api",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "secret",
        "UMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

ローカルの未リリースチェックアウトの場合でも、ビルドされたファイルを直接指定できます:

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

npmへの公開

このリポジトリは現在、npm CLIパッケージとして構成されています。

推奨されるリリースフロー:

pnpm test
pnpm build
pnpm pack --dry-run
npm login
pnpm publish

注意:

umami-mcpはnpm上で既に使用されているため、パッケージ名はumami-analytics-mcpに設定されています。
現在のlicenseは安全なプレースホルダーとしてUNLICENSEDになっています。寛容なライセンスが必要な場合は、実際の公開オープンソースリリース前に置き換えてください。
後で独自のnpmスコープで公開する場合は、package.jsonのnameフィールドのみを変更してください。

内部ドキュメント

このリポジトリで使用されているAPIサマリー: docs/umami-api.md

Umami MCP Server