PostHog MCPサーバーの使い方 — Claude Codeへの接続とCLIモードの仕組み
PostHog公式のMCPサーバーをClaude Codeに接続し、イベント分析・エラー調査・フィーチャーフラグ操作をエディタから行う手順をまとめます。
PostHogは、プロダクト分析・フィーチャーフラグ・エラートラッキング・セッションリプレイなどを1つのプラットフォームにまとめたオープンソースの分析基盤です。公式のMCPサーバーを使うと、Claude Codeからこれらの機能を自然言語で呼び出せます。「今週のエラー上位5件を出して」「新機能フラグを20%のユーザーに向けて作成して」といった指示だけで、ブラウザのダッシュボードを開かずに分析やフラグ操作が完結します。この記事では、Wizardコマンドを使った30秒でのセットアップから、認証方式の選び方、Claude Code特有のCLIモードの仕組みまでを扱います。
PostHog MCPサーバーとは
PostHog MCPサーバーは、https://mcp.posthog.com/mcp でホストされている無料のMCPエンドポイントです。接続自体とツール呼び出しは無料ですが、一部のツールは内部でLLMを使っており、その分はPostHog AI利用料として課金される場合があります。これらのAI搭載ツールは、組織設定でAIデータ処理が有効になっているときだけ利用できます。
対応クライアントはClaude Code・Claude Desktop・Cursor・Codex・VS Code・Windsurf・Zedなど、MCPに対応するものなら基本的に何でも使えます。サーバーはPostHogのプロキシとして動作し、分析データそのものは保存しません。クエリはユーザーのPostHogプロジェクトに対して実行され、結果がそのままAIクライアントへ返る仕組みです。サインインに使ったアカウントに応じて、US・EUどちらのデータリージョンかも自動で振り分けられます。
3つの接続方法を使い分ける
PostHog MCPサーバーへの接続方法は3通りあります。どれを選ぶかで、初期セットアップの手間とその後の使い勝手が変わります。
| 方法 | コマンド | 向いているケース |
|---|---|---|
| Wizard | コマンドnpx @posthog/wizard mcp add | 向いているケース最短で試したい・複数クライアントへまとめて導入したい |
| Claude Codeプラグイン | コマンドclaude plugin install posthog | 向いているケーススラッシュコマンド(/posthog:flags等)も併せて使いたい |
| 手動設定 | コマンドclaude mcp add --transport http ... | 向いているケース設定内容を自分で管理したい・CI等で再現したい |
PostHog Wizardは、PostHog Desktop・Cursor・Claude Code・Claude Desktop・Codex・VS Code・Zedへ一括でMCPサーバーを登録できる公式CLIです。迷ったらまずこれを実行すれば、対話形式でクライアントを選んで接続まで完了します。
npx @posthog/wizard mcp addClaude Codeにはプラグイン版もあります。同じMCPツール群に加えて、/posthog:flags /posthog:insights /posthog:errors /posthog:experiments といったスラッシュコマンドが使えるようになる点が違いです。
claude plugin install posthogインストール後は /mcp を実行し、ブラウザでのログインプロンプトに従って認証します。
手動でMCPサーバーを追加する
Wizardやプラグインを使わず、コマンド1行で直接登録することもできます。
claude mcp add --transport http posthog \
https://mcp.posthog.com/mcp -s user登録後、初回のツール呼び出し時にPostHogへのログインを求められます。認証にはOAuthを使うのが推奨経路で、Wizard経由ならそのまま動作します。OAuthに対応しないクライアントの場合は、MCP Serverプリセットで発行した個人APIキーをAuthorization: Bearerヘッダーに渡す方法に切り替えられます。エンタープライズプランでは、OktaやEntra IDなどのIdPを通じてMCPアクセスを一元管理する仕組み(ID-JAG)も用意されています。
複数のPostHogアカウント・組織・プロジェクトを横断したい場合は、1接続につき1アカウント・1組織・1プロジェクトが原則です。US・EUで別アカウントを使っているときは、リージョンごとに別のMCP接続を用意する必要があります。同一アカウント内で組織やプロジェクトを切り替えるだけなら、switch-organization・switch-projectという専用ツールが使えます。
アクセス範囲を絞る
エージェントにプロジェクトへの書き込みを許可する前に、権限を絞る設定を確認しておくと安全です。PostHog公式も「プロンプトインジェクションに注意し、実行前にツール呼び出しを必ず確認する」よう案内しています。
読み取り専用に制限するには、x-posthog-read-onlyヘッダーかreadonlyクエリパラメータをtrueにします。作成・更新・削除系のツールが一覧から除外され、読み取り系だけが残ります。
https://mcp.posthog.com/mcp?readonly=true利用するツールをカテゴリ単位で絞ることも可能です。featuresパラメータに、flags(フィーチャーフラグ)・insights(分析インサイト)・error_tracking(エラー監視)・experiments(A/Bテスト)などのカテゴリ名をカンマ区切りで渡します。
https://mcp.posthog.com/mcp?features=flags,dashboards,insights特定のプロジェクトに固定したいときは、x-posthog-project-idヘッダーかproject_idクエリパラメータでピン留めできます。プロジェクトを固定すると、誤って別プロジェクトを操作するリスクを避けられます。
CLIモードが数百個のツールを1本にまとめる仕組み
PostHog MCPサーバーの公式ツール一覧には、アクセス制御からワークフローまで72カテゴリー、合計968個のツールが列挙されています。これをクライアントがすべて個別のMCPツールとして読み込むと、接続直後のコンテキスト消費が膨らみます。
これに対応するため、サーバーは「CLIモード」と「Toolsモード」の2つの公開方式を持っています。Toolsモードは標準的なMCPの動作で、全ツールの名前とスキーマを接続時に一括で読み込みます。少数のクライアント(Cursorなど、大量のツールリストをネイティブに扱えるクライアント)がこちらを既定にしています。
Claude・Claude Code・Cowork・Codexを含む大半のクライアントは、CLIモードを既定として使います。CLIモードではexecという単一のツールだけが登録され、エージェントはコマンド文字列をexecに渡してツールを検索・確認・呼び出しします。
| コマンド | 役割 |
|---|---|
tools | 役割利用可能なツール名を一覧表示 |
search <正規表現> | 役割名前・タイトル・説明からツールを検索 |
info <ツール名> | 役割ツールの説明と入力スキーマを表示 |
schema <ツール名> [フィールド] | 役割特定フィールドのスキーマを深掘り |
call <ツール名> <JSON> | 役割JSON入力でツールを実行 |
エージェントは通常、searchかtoolsでツール名を見つけ、infoでスキーマを一度確認してからcallで実行する、という順序で動きます。execは1回の呼び出しにつき1コマンドしか受け付けません。複数のコマンドを改行で並べても、実行前にまとめて拒否されます。並列に複数回execを呼ぶことはできるので、複数の操作をまとめたいときはそちらを使います。
Claude Codeからできること
接続後は、分析・エラー調査・フラグ操作をすべて自然言語の指示で行えます。イベント分析では、トレンドクエリやパスクエリを直接実行できます。
- 「過去7日間に新規登録したユニークユーザー数を日別に出して」
- 「サインアップ後に最も多いユーザーの遷移パスは?」
- 「料金ページからチェックアウトまでの導線を見せて」
エラー調査では、スタックトレースの取得から外部トラッカーへの連携まで一連の操作をエージェントに任せられます。
- 「今週のプロジェクトでエラー上位5件を教えて」
- 「直近のクラッシュのスタックトレースを見せて、修正案を出して」
- 「このIssueを解決済みにして、今後発生する同種のTypeErrorはバックエンドチームに割り当てて」
フィーチャーフラグと実験の管理には、feature-flagsカテゴリーだけで27個のツールが用意されています。ロールアウト作成から段階的リリースのスケジューリングまでを1つの会話でこなせます。
- 「new-checkout-flowという名前で、20%のユーザーに有効なフィーチャーフラグを作って」
- 「controlが34%、variant_aが33%、variant_bが33%のマルチバリアントフラグhomepage-hero-testを作って」
- 「料金ページからチェックアウトへのコンバージョンを測定するA/Bテストを作成して」
SQLやHogQLで直接クエリを書きたい場面にも対応しています。「ロールアウト率が50%未満のフィーチャーフラグを全部探して」のような指示から、system.feature_flagsへのクエリを組み立てて実行します。
よくあるつまずき
プロンプトインジェクションへの警戒を怠らない。MCPツール呼び出しを経由してPostHogへの書き込みが行われるため、エージェントが外部コンテンツに埋め込まれた不正な指示に従ってしまうリスクがあります。破壊的な操作の前には必ず内容を確認する運用にします。CLIモードのcallコマンドには、破壊的なツールに対して--confirmが必須になる仕組みも入っています。
AI搭載ツールが想定外の課金につながることがある。感情分析やトレース要約など、内部でLLMを呼ぶツールは通常のAPIレート制限とは別に、より低い上限が個別に設定されています。頻繁に上限へ達する場合は、バッチエクスポートやエンドポイント経由でのデータ取得に切り替えるのが公式の案内です。
リージョンまたぎのアカウントは接続が2本必要になる。US・EUでアカウントを分けている場合、MCP接続はサインインしたアカウントのリージョンに自動で振り分けられます。両リージョンを使うなら、リージョンごとに個別の接続を用意しないと片方にしかアクセスできません。
OAuthで複数エントリを認可すると同じアカウントに紐づいてしまうことがある。クライアントがブラウザセッションを複数の接続エントリで共有していると、意図せず同じアカウントとして認可されるケースがあります。アカウントを厳密に分けたいときは、エントリごとに個人APIキーを発行する方法のほうが確実です。
まとめ
PostHog MCPサーバーは、npx @posthog/wizard mcp addかプラグインインストールで数十秒で接続でき、イベント分析・エラー調査・フィーチャーフラグ操作をClaude Codeの会話内で完結させられます。Claude Codeは既定でCLIモードを使うため、968個ある個別ツールのスキーマを毎回読み込む必要はなく、exec経由での検索・呼び出しでコンテキスト消費を抑えられます。書き込み権限を持たせる前には、読み取り専用モードやカテゴリ単位のツール制限で操作範囲を絞っておくと安全です。MCPサーバー自体をゼロから作る場合の手順はMCPサーバー自作ガイド、他の分析・データ基盤系サーバーとの比較はMongoDB MCPサーバーガイドやTurso MCPサーバーガイドも参考になります。