plausible-mcp

Plausible Analytics 用の MCP サーバー — Model Context Protocol をサポートする任意の AI ツールから、トラフィック、コンバージョンの照会、期間の比較ができます。

次のような質問をしたいチーム向けに作られています:

• 「火曜日のデプロイは /pricing へのトラフィックに影響しましたか？」

• 「今月の /blog のサインアップコンバージョン率は？」

• 「今週の直帰率は先週と比べてどうですか？」

ツール

すべてのクエリツールは読み取り専用で、readOnlyHint: true で注釈されています。

ホスト型デプロイメントではさらに send_feedback が公開され、サーバー自体に関するフィードバック（紛らわしいエラー、不足している機能）をメンテナの Sentry User Feedback 受信トレイに送信します。これはサーバーが Sentry で実行されている場合（enableFeedbackTool）にのみ登録されます。

Related MCP server: umami-mcp-server

クイックスタート

リモート（ホスト型）

ホスト型インスタンスは https://plausible-mcp.sentry.dev で利用できます。

独自の Plausible API キーを使用する場合（任意のユーザー）:

claude mcp add --transport http plausible https://plausible-mcp.sentry.dev/mcp --header "Authorization: Bearer YOUR_PLAUSIBLE_API_KEY"

URL を --header の前に置いてください。--header は可変長引数なので、最後に置くと URL を飲み込んでしまい、CLI が error: missing required argument 'commandOrUrl' で失敗します。

または、MCP クライアント設定（Claude Desktop、Cursor など）に手動で追加します:

{
  "mcpServers": {
    "plausible": {
      "url": "https://plausible-mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

Sentry 社員（OAuth 2.1 + Cloudflare Access 経由）:

/internal エンドポイントは OAuth 2.1 サーバーです — API キーは不要です。OAuth 対応の MCP クライアント（Cowork、Claude.ai コネクタ、Claude Desktop）でリモート/カスタムコネクタとして追加してください:

https://plausible-mcp.sentry.dev/internal

クライアントは OAuth エンドポイントを自動的に検出し、Sentry SSO（Cloudflare Access）を経由して認証し、@sentry.io の ID のみがアクセスを許可されます。クエリは共有のサーバーサイド Plausible API キーに対して実行されるため、キーを扱う必要はありません。

ホスト型の /internal（plausible-mcp.sentry.dev）は Sentry 専用で、組織外では使用できません。別の組織で /internal を実行するには、セルフホスト して ALLOWED_EMAIL_DOMAIN を自分のドメインに設定してください。（公開の /mcp 持ち込みキーエンドポイントにはそのような制限はありません。）

ローカル（STDIO）

ローカルで実行したい場合は、Node.js 20 以降を使用してください:

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
pnpm build

Claude Code に追加:

claude mcp add plausible -e PLAUSIBLE_API_KEY=your-key -- node /path/to/plausible-mcp/dist/index.js

または Claude Desktop（claude_desktop_config.json）:

{
  "mcpServers": {
    "plausible": {
      "command": "node",
      "args": ["/path/to/plausible-mcp/dist/index.js"],
      "env": {
        "PLAUSIBLE_API_KEY": "your-key"
      }
    }
  }
}

セルフホスティング（Cloudflare Workers）

独自のインスタンスをデプロイ:

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
npx wrangler deploy

ワーカーは 2 つのエンドポイントを公開します:

• /mcp — 持ち込みキー。各ユーザーは独自の Plausible API キーを Authorization: Bearer ヘッダーで渡します。サーバー側で共有シークレットは不要です。ヘッダー対応の MCP クライアント（Claude Code、Cursor、MCP Inspector）で動作します。

• /internal — 管理コネクタ（Cowork、Claude.ai）用の Access 保護 MCP エンドポイント。Cloudflare Access アプリケーション（Managed OAuth）がワーカーのホスト名全体を前面に置きます（下記の制約を参照）。Access はクライアントとの OAuth 2.1 ハンドシェイクを実行し、各リクエストを Cf-Access-Jwt-Assertion ヘッダー付きでワーカーに転送します。ワーカーはそのヘッダーを検証し、共有のサーバーサイド Plausible API キーを使用してクエリを実行します。Access は ALLOWED_EMAIL_DOMAIN（デフォルトは sentry.io）のメールドメインに制限されます — セルフホスト時は Sentry に関連付けられません。自分のドメインに設定してください。

Managed OAuth アプリケーションはパスなしのベアホスト名をカバーする必要があるため（OAuth を有効にすると Cloudflare はパスを拒否します — domain can not have a path if oauth is configured）、/mcp もゲートされます。持ち込みキーの /mcp エンドポイントを公開のままにするには、/mcp パスにスコープされた 2 つ目のより具体的な Access アプリケーションを Bypass ポリシーで追加します。Cloudflare は最も具体的なホスト名+パスを最初に一致させるため、/mcp リクエストは Access を完全にバイパスし、それ以外はすべて OAuth を通過します。両方のアプリは 1 つのホスト名に存在します。別のサブドメインは不要です。

ベータ版 / クライアント要件。 Cloudflare Access Managed OAuth はベータ版であり、RFC 8707（リソースインジケータ）をサポートする MCP クライアントが必要です。このパスに依存する前に、コネクタがサポートしていることを確認してください。

/internal エンドポイントの設定（Cloudflare Access Managed OAuth）

ワーカーはOAuth サーバーを実行しません — Cloudflare Access が認可サーバーです。OAUTH_KV も、クッキーキーも、OAuth クライアント ID/シークレットもありません。同じホスト名に2 つの Access アプリケーションを作成します。

1. ベアホスト名で Managed OAuth アプリケーションを作成（Zero Trust → Access → Applications）: ドメインが plausible-mcp.sentry.dev でパスなしのセルフホストアプリまたはMCP サーバーアプリケーション。

   • ⚠️ /internal にスコープしないでください。 Managed OAuth を有効にすると、Cloudflare はパスを access.api.error.invalid_request: domain can not have a path if oauth is configured で拒否します。アプリはホスト全体である必要があります。ワーカーが /internal ルートを自身で強制します。

   • メールドメイン（例: @acme.com）と ID プロバイダーに制限する Access ポリシー（アクション Allow）を追加します。

   • Managed OAuth を有効にし（詳細設定 → Managed OAuth）、許可されたリダイレクト URI をコネクタの実際のコールバックに設定します — Claude/Cowork の場合は https://claude.ai/api/mcp/auth_callback。公開 HTTPS コールバックは必ずリストに含める必要があります。含めないと Dynamic Client Registration が invalid_client_metadata: redirect_uri is not allowed by the account configuration で失敗します。ループバック（http://localhost:*）コールバックはデフォルトで許可されます。

   • アプリケーションの AUD タグをコピー → これが CF_ACCESS_AUD になります。

2. 2 つ目のパススコープの Bypass アプリケーションで /mcp を切り出します。 ステップ 1 がホスト全体をカバーするため、/mcp（持ち込みキー）もゲートされます。別のセルフホストアプリを作成し、ドメイン plausible-mcp.sentry.dev パス mcp、Managed OAuth オフ、ポリシーのアクションは Bypass、セレクターは Everyone にします。

   • Bypass ≠ Allow: Allow ポリシーは対話型ログインを強制します（クライアントはログインページへの HTML 302 を受け取り、Unexpected content type: text/html で失敗します）。Bypass のみが認証なしでリクエストを通過させ、ワーカー自身の Bearer キーチェックが適用されます。

3. ワーカーシークレットを設定:

   npx wrangler secret put PLAUSIBLE_API_KEY          # shared key for /internal queries
   npx wrangler secret put SENTRY_DSN                 # optional — the Worker's own telemetry

   CF_ACCESS_TEAM_DOMAIN と CF_ACCESS_AUD はシークレットではありません — 公開 JWKS URL とアプリケーション識別子です。そのためステップ 4 の [vars] に入ります。

4. wrangler.toml の [vars] を設定:

   • CF_ACCESS_TEAM_DOMAIN — https://<team>.cloudflareaccess.com、末尾スラッシュなし。Cf-Access-Jwt-Assertion の JWKS と発行者を検証します。

   • CF_ACCESS_AUD — ステップ 1 でコピーした AUD タグ。

   • ALLOWED_EMAIL_DOMAIN — サインインを許可するメールドメイン（カンマ区切り、@ は省略可能、デフォルト sentry.io）。ステップ 1 の Access ポリシーに加えてコードで強制されるため、自分のドメインに設定してください — そうしないとすべてのログインが拒否されます。

   • MCP_ALLOWED_HOSTNAMES — MCP エンドポイントが受け入れるホスト名（カンマ区切り）。plausible-mcp.sentry.dev をワーカーのホスト名に置き換え、wrangler dev を使用する場合は localhost エントリを維持します。

   • MCP_ALLOWED_ORIGIN_HOSTNAMES — /internal を呼び出せるブラウザ Origin ホスト名（カンマ区切り）。非ブラウザクライアントは Origin ヘッダーを送信しません。

5. デプロイ（npx wrangler deploy）し、RFC 8707 対応の MCP クライアントを https://<your-worker-host>/internal にポイントします。

トラブルシューティング。 これらはすべて Cloudflare Access の設定であり、ワーカーではありません — リクエストがワーカー（およびその Sentry スパン）に到達するのは、Access が転送した後だけです:

設定

Worker では、/mcp エンドポイントはサーバー側キーを必要としません — 各ユーザーが Authorization: Bearer で自分のキーを渡します。/internal エンドポイントは Cloudflare Access Managed OAuth で保護され、共有のサーバー側 PLAUSIBLE_API_KEY シークレットを使用します（セルフホスティング を参照）。

Plausible API

このサーバーは Plausible Stats API v2（POST /api/v2/query）をラップしています。Plausible Cloud と セルフホスト の両方で動作します。

対応メトリクス

visitors、visits、pageviews、views_per_visit、bounce_rate、visit_duration、events、scroll_depth、percentage、conversion_rate、group_conversion_rate、average_revenue、total_revenue、time_on_page

対応ディメンション

event:page、event:goal、event:hostname、visit:entry_page、visit:exit_page、visit:source、visit:referrer、visit:channel、visit:utm_medium、visit:utm_source、visit:utm_campaign、visit:utm_content、visit:utm_term、visit:device、visit:browser、visit:browser_version、visit:os、visit:os_version、visit:country、visit:region、visit:city、visit:country_name、visit:region_name、visit:city_name

*_name の地理ディメンションは人間が読める名前（例：「カナダ」）を返します。通常の visit:country/region/city は ISO/Geoname コードを返します。

フィルタリング

すべてのクエリツールは property_filters を受け付けます。名前とは異なり、組み込みディメンションとカスタムイベントプロパティの両方でフィルタリングします。各エントリは { "property", "operator", "values" } の形式です：

• property — 組み込みディメンション（例：visit:channel、visit:source、event:page）またはカスタムプロパティの素の名前（"plan" は event:props:plan を対象にします）。

• operator — is、is_not、contains、contains_not（デフォルトは is）。event:goal は is と contains のみサポートします。

• 複数のエントリは AND で結合されます。page/goal のショートカットパラメータも同様です。同じ呼び出しでショートカットと property_filters の両方から event:page/event:goal を対象にすることは拒否されます — どちらか一方を使用してください。

例えば、オーガニック検索トラフィックの上位ページを取得する場合：get_breakdown に dimension: "event:page" と property_filters: [{ "property": "visit:channel", "values": ["Organic Search"] }] を渡します。

カスタムプロパティ

サイトは独自のカスタムイベントプロパティを送信します。これらは event:props:<name> として扱われます。サイト固有のものなので、固定リストはありません。

• カスタムプロパティで分類する：get_breakdown に event:props:<name> の dimension を渡します（例：event:props:plan）。

• カスタムプロパティでフィルタリングする：property_filters に素の名前を渡します。例：[{ "property": "plan", "operator": "is", "values": ["pro"] }]。

開発

pnpm install
pnpm build         # TypeScript compilation
pnpm test          # Run unit + integration tests
pnpm test:watch    # Watch mode

MCP Inspector でのテスト

pnpm build
PLAUSIBLE_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

LLM 評価

自然言語の分析クエリに対してモデルが正しいツールを選択するかを検証します。OpenRouter 経由で実行されるため、任意のツール呼び出し対応モデルで動作します — デフォルトは anthropic/claude-sonnet-5 です：

OPENROUTER_API_KEY=sk-or-... pnpm eval
OPENROUTER_MODEL=openai/gpt-5 OPENROUTER_API_KEY=sk-or-... pnpm eval  # try another model

アーキテクチャ

src/
├── index.ts              # STDIO entry point (local use)
├── worker.ts             # Cloudflare Worker entry point (remote)
├── env.ts                # Worker environment bindings
├── cf-access.ts          # Verifies the Cloudflare Access assertion on /internal
├── server.ts             # Creates McpServer, registers all tools
├── plausible.ts          # PlausibleClient — standalone API client
├── schemas.ts            # Shared Zod schemas and filter helpers
├── errors.ts             # UserFacingError and tool-error reporting
├── telemetry.ts          # Pure classifiers — route, MCP request kind, client family
├── mcp-telemetry.ts      # Records MCP client info onto the active span
├── redaction.ts          # Strips PII from Sentry events on the BYOK path
└── tools/
    ├── get-timeseries.ts
    ├── get-breakdown.ts
    ├── get-conversions.ts
    ├── compare-periods.ts
    └── send-feedback.ts

PlausibleClient は MCP への依存がゼロで、単体で使用できます。

可観測性とデータ収集

Worker はエンドポイントに応じたプライバシーポリシーで Sentry にレポートします：

• /mcp（キー持ち込み） — 完全に匿名。ツールの入力と出力は記録されません（そのデータは呼び出し元とそのキーに属します）。ID は付与されず、取り込み時に推測されたクライアント IP は削除されます（src/redaction.ts）。運用テレメトリのみが残ります：ツール名、スパンのタイミング、失敗。

• /internal（SSO ゲート付き） — 属性付き。リクエストには認証済みの @sentry.io メールアドレスが付与され（Sentry.setUser）、ツールの入力/出力は共有サーバー側キーの属性追跡と不正使用トレースのために記録されます（recordToolIO）。

Authorization / Cookie / Cf-Access-Jwt-Assertion ヘッダーは、両方のパスでスパンから削除されます。念のためのバックストップとして、Sentry プロジェクトの Security & Privacy 設定で Prevent Storing of IP Addresses を有効にしてください。

ライセンス

MIT — LICENSE を参照。