PostHog MCPサーバーの使い方 — Claude Codeへの接続とCLIモードの仕組み

PostHogは、プロダクト分析・フィーチャーフラグ・エラートラッキング・セッションリプレイなどを1つにまとめた分析基盤です。公式のMCPサーバーを使うと、Claude Codeからこれらの機能を自然言語で呼び出せます。「今週のエラー上位5件を出して」「新機能フラグを20%のユーザーに向けて作成して」といった指示だけで、ダッシュボードを開かずに分析やフラグ操作が済みます。

接続自体は npx @posthog/wizard mcp add の1行で終わります。つまずきやすいのは、その後の認証方式の選び方、書き込み権限の絞り方、複数アカウントの扱いです。ここでは接続から権限設計、Claude Code特有のCLIモードまでを順に説明します。

何ができて、いくらかかるか

PostHog MCPサーバーは、https://mcp.posthog.com/mcp でホストされている無料のMCPエンドポイントです。接続とツール呼び出しは無料で、クエリが読むデータ量には通常のPostHogの利用料金がかかります。一部のツールは内部でLLMを使い、その分はPostHog AIの利用料として課金される場合があります。

AIを使うツールは、組織設定でAIデータ処理を有効にしているときだけ使えます。無効なあいだは、これらのツールがMCPクライアントに公開されません。

対応クライアントはClaude Code・Claude Desktop・Cursor・Codex・VS Code・Windsurf・Zedなど、MCPに対応するものなら基本的に使えます。サーバーはPostHogのプロキシとして動き、分析データそのものは保存しません。クエリはPostHogのプロジェクトに対して実行され、結果がそのままAIクライアントへ返ります。US・EUどちらのデータリージョンに届くかは、サインインしたアカウントで自動的に決まります。

まず試す:3つの接続方法から選ぶ

接続方法は3通りあります。選び方の基準は、最短で試したいのか、スラッシュコマンドも欲しいのか、設定を自分で管理したいのかです。

Wizardは、PostHog Desktop・Cursor・Claude Code・Claude Desktop・Codex・VS Code・ZedへMCPサーバーを直接登録できる公式CLIです。迷ったらまずこれを実行します。

npx @posthog/wizard mcp add

プラグイン版を選ぶ場合は、次のコマンドを使います。

claude plugin install posthog

どちらの場合も、インストール後にClaude Codeで /mcp を実行し、ブラウザのログイン画面に従って認証します。

手動で追加すると設定ファイルに何が書かれるか

公式の手動セットアップは、次の1行です。

claude mcp add --transport http posthog \
  https://mcp.posthog.com/mcp -s user

-s user は、全プロジェクトで使えるユーザースコープへの登録を指します。claude mcp add --help(v2.1.287)では、--scope の既定値は local と表示されます。つまり -s を省くと、いま開いているプロジェクトだけに登録されます。

では、クエリパラメータ付きのURLをプロジェクトスコープ(-s project)で追加すると、どうなるでしょうか。v2.1.287では次のとおりです。

claude mcp add --transport http posthog \
  "https://mcp.posthog.com/mcp?readonly=true&features=flags,insights" \
  -s project

画面には Added HTTP MCP server posthog with URL: https://mcp.posthog.com/mcp to project config と出ます。クエリ部分は表示から省かれますが、プロジェクト直下の .mcp.json には残ります。

{
  "mcpServers": {
    "posthog": {
      "type": "http",
      "url": "https://mcp.posthog.com/mcp?readonly=true&features=flags,insights"
    }
  }
}

次に、-H でヘッダーを付けた場合です。-H "Authorization: Bearer phx_example" と -H "x-posthog-project-id: 12345" を指定して追加すると、画面には "Authorization": "[REDACTED]" と伏せ字で出ます。ところが .mcp.json には、キーがそのまま書き込まれます。

"posthog-eu": {
  "type": "http",
  "url": "https://mcp.posthog.com/mcp",
  "headers": {
    "Authorization": "Bearer phx_example",
    "x-posthog-project-id": "12345"
  }
}

プロジェクトスコープの .mcp.json は、チームで共有するためにバージョン管理へ入れる前提のファイルです。個人APIキーを -H で直接渡すと、キーがリポジトリに混ざります。

.mcp.json ではヘッダーの値に ${VAR} と書くと環境変数が展開されます。"Authorization": "Bearer ${POSTHOG_API_KEY}" のように書けば、キーの実体はリポジトリの外に置けます。

ただし ANTHROPIC_API_KEY のようなClaude Code自身や各クラウドの認証情報の変数名は、リモートサーバーの url と headers では空として扱われます。PostHogのキーには、POSTHOG_API_KEY のように独自の名前を付けます。

OAuthが使えないとき、複数アカウントを使うとき

認証は、OAuthが推奨の経路です。Wizard経由なら、そのまま動きます。クライアントがOAuthに対応しない場合は、MCP Server プリセットで個人APIキーを発行し、Authorization: Bearer ヘッダーに渡す方法に切り替えます。このプリセットのキーは、特定のプロジェクトにアクセスが限られます。

エンタープライズプランでは、OktaやEntra IDなどのIdPを通じてMCPアクセスを一元管理する仕組み(ID-JAG)も使えます。ユーザーごとのOAuthやキーの発行は不要になります。

1つの接続は、1アカウント・1組織・1プロジェクトが原則です。複数を扱うときは、状況ごとに答えが変わります。

最後の行には理由があります。クライアントがブラウザセッションを複数の接続で共有していると、すべてを同じアカウントで認可してしまう場合があるためです。キーは1アカウントに属するので、これを防げます。

複数の接続は、サーバー名を変えて別々に登録します。名前はエージェントから見える名前なので、posthog-acme-us のように、どのコンテキストを指すかが分かる名前にします。上で見たように、claude mcp add を名前違いで繰り返すと、.mcp.json に別のエントリとして並びます。

切り替えツールは手軽ですが、エージェントが「いま自分がどのプロジェクトにいるか」を覚えている必要があります。思い違いがあれば、書き込みが別のプロジェクトへ飛びます。

書き込みを許す前に権限を絞る

PostHog公式は、プロンプトインジェクションに注意し、実行前にツール呼び出しを必ず確かめるよう案内しています。外部コンテンツに埋め込まれた不正な指示に、エージェントが従うおそれがあるためです。権限を絞る手段は、読み取り専用化・カテゴリ指定・ツール名指定・プロジェクト固定の4つです。

読み取り専用にするには、x-posthog-read-only ヘッダーか readonly クエリパラメータを true(または 1)にします。両方を指定した場合は、ヘッダーが優先されます。作成・更新・削除系のツールが一覧から除かれ、読み取り系だけが残ります。

https://mcp.posthog.com/mcp?readonly=true

使うツールをカテゴリ単位で絞るには、features パラメータにカテゴリ名をカンマ区切りで渡します。flags(フィーチャーフラグ)・insights(分析インサイト)・error_tracking(エラー監視)・experiments(A/Bテスト)などがあり、ハイフンとアンダースコアは同じ扱いです。

https://mcp.posthog.com/mcp?features=flags,dashboards,insights

ツールを1つずつ指定する tools パラメータもあります。features と同時に使うと和集合になります。たとえばフラグのカテゴリ全体に加えて、ダッシュボードの取得だけを足せます。

https://mcp.posthog.com/mcp?features=flags&tools=dashboard-get

プロジェクトの固定は、x-posthog-project-id ヘッダーか project_id クエリパラメータで行います。組織の固定は、x-posthog-organization-id ヘッダーか organization_id パラメータです。

projectId を渡すと switch-organization と switch-project の両方が、組織だけなら switch-organization が、ツール一覧から外れます。エージェントが自分で行き先を変えられなくなるため、誤って別プロジェクトへ書き込む経路が閉じます。

大量のツールがコンテキストを圧迫しない仕組み

PostHog MCPサーバーのツール一覧は、アクセス制御からワークフローまで74カテゴリー、合計1,083個に及びます。数が多く、すべて個別のMCPツールとして読み込むと、接続した直後からコンテキストを大きく消費します。

この問題に対して、サーバーは2つの公開方式を持ちます。モードはクライアントから自動で判定されます。

大量のツール一覧をネイティブに扱えるクライアントは、Toolsモードが既定です。既定は x-posthog-mcp-mode ヘッダーか mode クエリパラメータ(cli または tools)で上書きできます。両方を指定した場合は、ヘッダーが優先されます。

CLIモードでは、エージェントは exec に次のコマンドを渡します。

exec は1回の呼び出しにつき1コマンドしか受け付けません。複数のコマンドを改行で並べても、実行前にまとめて拒否されます。並列に複数回 exec を呼ぶのは問題ないので、複数の操作をまとめたいときはそちらを使います。

Claude Codeから実際に頼めること

接続後は、分析・エラー調査・フラグ操作をすべて自然言語で指示できます。

イベント分析では、トレンドクエリやパスクエリを直接実行できます。

• 「過去7日間に新規登録したユニークユーザー数を日別に出して」
• 「サインアップ後に最も多いユーザーの遷移パスは?」
• 「料金ページからチェックアウトまでの導線を見せて」

エラー調査では、スタックトレースの取得から外部トラッカーへの連携までを任せられます。

• 「今週のプロジェクトでエラー上位5件を教えて」
• 「直近のクラッシュのスタックトレースを見せて、修正案を出して」
• 「このIssueを解決済みにして、今後発生する同種のTypeErrorはバックエンドチームに割り当てて」

フィーチャーフラグと実験の管理は、ロールアウトの作成から実験の設定までが同じ会話で進みます。

• 「new-checkout-flowという名前で、20%のユーザーに有効なフィーチャーフラグを作って」
• 「controlが34%、variant_aが33%、variant_bが33%のマルチバリアントフラグhomepage-hero-testを作って」
• 「料金ページからチェックアウトへのコンバージョンを測定するA/Bテストを作成して」

マルチバリアントのフラグは、各バリアントの割合が整数で、合計が100になる必要があります。33%を3つ並べると99%になるため、上の例は34・33・33と振っています。

SQLやHogQLで直接クエリを書く場面にも対応します。「ロールアウト率が50%未満のフィーチャーフラグを全部探して」と頼むと、system.feature_flags に対するクエリが組み立てられます。

よくあるつまずき

他のプロジェクトでPostHogのツールが出ない。 -s を付けずに追加すると、既定のローカルスコープになり、追加したプロジェクトでしか使えません。どのプロジェクトでも使いたいなら、-s user で追加し直します。

環境変数を使ったのに認証が通らない。 .mcp.json の ${POSTHOG_API_KEY} が未設定で、既定値もないとき、Claude Codeは claude mcp list と /mcp で変数名を警告します。サーバーは読み込まれますが、${POSTHOG_API_KEY} という文字列のまま送られます。変数を設定するか、${POSTHOG_API_KEY:-既定値} の形で既定値を足します。

AI搭載ツールだけ上限に当たる。感情分析やトレース要約のように内部でLLMを呼ぶツールには、より低い上限が別に設けられています。通常のツールはAPIと同じレート制限で、この制限は組織内の全ユーザーとキーをまとめた、チーム単位の値です。頻繁に上限へ達するなら、バッチエクスポートやエンドポイント経由でデータを取る構成も案内されています。

破壊的な操作が止まる。エージェントが --confirm を付け忘れて止まっているときは、対象の内容を見たうえで、付けて再実行させます。

まとめ

試すだけなら npx @posthog/wizard mcp add で足ります。チームで共有する .mcp.json に載せるなら、先に読み取り専用化かカテゴリ指定で操作範囲を絞り、キーは環境変数経由で渡す構成になります。

MCPサーバーをゼロから作る場合の手順はMCPサーバー自作ガイドにあります。ほかのデータ基盤系サーバーの使い方は、MongoDB MCPサーバーガイドやTurso MCPサーバーガイドが参考になります。