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実装

• 明確な構造化ツール出力と明示的なエラーカテゴリ

Related MCP server: umami-mcp-server

要件

• 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

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

1. APIキーモード

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

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

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での推奨スモークテスト:

1. umami_ping

2. umami_list_websites

3. umami_get_stats

4. 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