plausible-mcp

組織の全員がClaudeからPlausible Analyticsにクエリを実行できるようにするMCPサーバーです。

1つのデプロイで組織全体をまかなえます。サーバー側に1つのPlausible APIキーを保持し、各人はGoogleで認証されるため、誰も自分のキーを持つ必要がなく、個別にアクセス権を付与する必要もありません。ALLOWED_DOMAINS に自分のGoogle Workspaceドメインを設定すれば、そのドメインのアドレスを持つ人は誰でも、最初の接続時に利用できます。そのドメイン外の同僚は、ALLOWED_EMAILS に1件ずつ追加していきます。

チーム向けのアナリティクスを運用していて、あなたに数値を尋ねてもらうのではなく、メンバー自身に数値を読んでもらいたいなら、これがまさにそのためのものです。

認証の仕組み

Claudeは、OAuth 2.1の動的クライアント登録を用いてこのサーバーに自分自身を登録します。Googleは動的クライアント登録をサポートしていないため、このサーバーが自ら認可サーバーとして機能し、ユーザー側のログインはGoogleに委任されます。

Googleは、その人が誰であるかを特定します。その人があなたのアナリティクスを読んでよいかどうかは決定しません。ミドルウェアは、ツールが呼び出されるたびに、呼び出し元の検証済みメールアドレスを ALLOWED_DOMAINS と ALLOWED_EMAILS に対してチェックします。どちらも設定しない場合、サーバーは起動を拒否します。

ALLOWED_DOMAINS は、この仕組みを組織全体に広げるための設定です。検証済みメールアドレスのドメインと完全一致で照合されるため、example.com は alice@example.com を許可しますが、alice@evil-example.com や alice@example.com.evil.com は許可しません。

アクセスを取り消すには、対象者を ALLOWED_EMAILS または ALLOWED_DOMAINS から外して再デプロイしてください。Googleアカウントを停止すれば再ログインできなくなりますが、許可リストはこのサーバーが署名したトークンのクレームを読み込むため、発行済みのトークンは有効期限が切れるまで動作し続けます。JWT_SIGNING_KEY をローテーションすると、全員をサインアウトさせる代わりに、すべてのトークンを即座に無効化できます。

Related MCP server: Plausible MCP

ツール

• query はStats API v2のクエリを実行します。異なるディメンションでグループ化すると、同じツールで時系列、内訳、ゴールコンバージョンを取得できます。2つの期間を比較するには、期間ごとに1回呼び出します。

• list_sites は、site_id として渡せるサイトのドメインを返します。

• usage_stats は、誰がサーバーを利用したか、どの程度利用したか、どのアカウントが拒否されたかを報告します。

利用状況の追跡

許可リストのミドルウェアは、チェックしなければならないため、各呼び出し元のメールアドレスを参照します。ユーザー単位の呼び出し回数、最初と最後に観測された時刻、ツールごとの内訳を、USAGE_PATH が指すボリュームに記録します。拒否されたアカウントは別枠でカウントされるため、許可リスト外の人が接続を試みていることを検出できます。

このデータは usage_stats ツールで読み取れます。許可リストに載っている人なら誰でも、全ユーザーの行を確認できます。USAGE_PATH を未設定にすれば、追跡はオフになります。

設定

コピーして使える形での一覧は .env.example を参照してください。

デプロイ

リポジトリには fly.toml が含まれているため、以下の手順は Fly.io を対象にしています。ただし、このサーバーにはFly固有の要素はありません。書き込み可能なディレクトリと上記の環境変数が必要な、単なる1つのコンテナです。手順内の YOUR-APP は自分のアプリ名に置き換えてください。

1. Google CloudコンソールでOAuthクライアントを作成します。Webアプリケーションを選択し、認証されたリダイレクトURIに https://YOUR-APP.fly.dev/auth/callback を設定します。URIは正確に一致している必要があります。

2. アプリとボリュームを作成します:

   fly apps create YOUR-APP --org YOUR-ORG
   fly volumes create plausible_mcp_data --app YOUR-APP --region fra --size 1 --yes

   fly launch ではなく fly apps create を使ってください。fly launch は fly.toml を再生成し、ボリュームマウントとヘルスチェックを破棄します。

3. fly.toml の app を自分のアプリ名に設定します。

4. 設定を行います。BASE_URL と ALLOWED_DOMAINS はデプロイごとに異なるため、fly.toml ではなくここに設定します。リポジトリにプレースホルダーをコミットしてしまうと、次のデプロイで実際の値が上書きされてしまうからです。

   fly secrets set --app YOUR-APP \
     BASE_URL=https://YOUR-APP.fly.dev \
     ALLOWED_DOMAINS=your-domain.org \
     GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com \
     GOOGLE_CLIENT_SECRET=GOCSPX-xxx \
     PLAUSIBLE_API_KEY=xxx \
     JWT_SIGNING_KEY="$(openssl rand -hex 32)"

   JWT_SIGNING_KEY は安定させてください。変更すると全員がサインアウトします。

5. fly deploy --ha=false

   --ha=false を付けないと、Flyが2つのマシンを起動する場合があります。それぞれが自分のボリュームを持つことになるため、あるマシンに登録されたサインインは、次のリクエストが別のマシンに届くと失敗します。

Claudeに追加する

チーム全体に追加するには、claude.aiで 設定 > コネクタ に移動し、カスタムコネクタを追加 を選択して、https://YOUR-APP.fly.dev/mcp を入力します。各ユーザーは、最初に利用するときGoogleでサインインします。

Claude Codeに追加するには:

claude mcp add --transport http plausible https://YOUR-APP.fly.dev/mcp

ローカルで実行する

uv venv && uv pip install -r pyproject.toml
cp .env.example .env    # then fill it in
set -a && source .env && set +a
python server.py

ローカルのサインインフローをテストするには、GoogleクライアントのリダイレクトURIに http://localhost:8000/auth/callback を追加してください。テストは python test_server.py で実行します。OAuthフローとツールを手動で試すには、npx @modelcontextprotocol/inspector を使ってください。

ライセンス

MIT — LICENSE をご覧ください。