Plausible Analytics MCP

plausible-mcp

AI コーディングエージェントや LLM ハーネス向けの、高速でプライバシーを最優先する Plausible Analytics Model Context Protocol（MCP）サーバーです。Plausible Cloud とセルフホストの Plausible の両方でシームレスに動作します。

クイックスタート

uvx で実行する（Python）

export PLAUSIBLE_API_KEY="your_api_key_here"
uvx plausible-mcp

npx で実行する（Node / npm ブリッジ）

export PLAUSIBLE_API_KEY="your_api_key_here"
npx -y plausible-analytics-mcp

環境設定

変数	説明	デフォルト
PLAUSIBLE_API_KEY	Plausible Stats/Sites API トークン	必須（またはツールの token 引数で指定）
PLAUSIBLE_BASE_URL	セルフホストの Plausible のベース URL	https://plausible.io
DO_NOT_TRACK	1 に設定すると匿名テレメトリーを無効化	0

API キーの取得方法

1. Plausible（Cloud またはセルフホストのインスタンス）にログインします。
2. Settings（ユーザープロフィールメニュー） -> API Keys に移動します。
3. + New Key をクリックし、mcp-agent という名前を付けて、トークンをコピーします。
4. PLAUSIBLE_API_KEY="your_token" としてエクスポートします。

利用可能なツール

ツール	説明
get_aggregate_stats(site_id, date_range="30d", metrics=None, token=None)	訪問者数、ページビュー数、直帰率、セッション時間の概要
get_breakdown(site_id, property_name="event:page", date_range="30d", limit=20, token=None)	ページ、トラフィックソース、国、ブラウザー、OS、デバイス別の指標
get_realtime_visitors(site_id, token=None)	現在サイトを訪問中のアクティブな訪問者数
get_timeseries(site_id, date_range="30d", interval="date", token=None)	グラフ作成用の日次または月次の傾向データポイント
doctor(token=None)	Plausible API への接続をテストし、設定された API トークンを検証
skills_list()	動的な分析プレイブックと手法ガイドを一覧表示
skill_read(name)	名前で指定した完全な Markdown プレイブックを取得（例：plausible-overview、analytics-recipes）
check_for_updates()	PyPI で新しいバージョンを確認し、アップグレードコマンドを表示

エラー吸収標準

エージェントに返されるエラーは、明示的に分類されます。

• [INPUT_FIXABLE]：パラメーターエラー（例：site_id の誤記、不明なディメンション）。引数を修正して再試行してください。
• [ENVIRONMENT_FIXABLE: STOP & ASK HUMAN]：API キーがない、期限切れ、または認証されていない状態です。手順に沿った設定方法をユーザーに提示してください。
• [TRANSIENT]：上流のレート制限（HTTP 429）またはネットワークの一時的な問題です。少し待ってから再試行してください。

MCP クライアントの設定

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "plausible": {
      "command": "uvx",
      "args": ["plausible-mcp"],
      "env": {
        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

または npm ブリッジを使用：

{
  "mcpServers": {
    "plausible": {
      "command": "npx",
      "args": ["-y", "plausible-analytics-mcp"],
      "env": {
        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

ライセンス

MIT License。詳細は LICENSE をご覧ください。