Google Analytics MCP 連携による自然言語分析サービスの構築

はじめに

本記事では、Google Analytics 4（GA4）の公式 Model Context Protocol（MCP）サーバーと連携し、AI モデルを活用してウェブサイトを自然言語で分析できるサービスの技術的な実装について解説します。

特に、Google Analytics MCP サーバーとの接続ロジックを中心に、実際の実装コードを交えながら詳しく説明していきます。

サービス概要

このサービスは、以下の特徴を持つ GA4 データ分析チャットボットです：

自然言語によるデータ分析：ユーザーが日本語で質問すると、AI が GA4 データを取得・分析して回答
複数プロパティの横断分析：複数の GA4 プロパティを選択して比較分析が可能
リアルタイムグラフ生成：Chart.js を使用した動的なデータビジュアライゼーション
MCP プロトコルの活用：Google Analytics の公式 MCP サーバーを利用した安全なデータアクセス

技術スタック

{
  "フレームワーク": "Next.js 15 (App Router)",
  "AIライブラリ": "Vercel AI SDK",
  "MCPクライアント": "@modelcontextprotocol/sdk",
  "認証": "Auth.js (NextAuth v5)",
  "データベース": "Neon Serverless Postgres",
  "言語": "TypeScript"
}

Model Context Protocol (MCP) とは？

MCP は、AI アプリケーションが外部ツールやデータソースと安全に連携するための標準プロトコルです。

MCP の利点

標準化されたインターフェース：どのツールも同じ方法で呼び出せる
セキュリティ：認証情報の安全な管理
拡張性：新しいツールを簡単に追加可能
型安全性：スキーマベースのパラメータ検証

Google Analytics MCP 接続の全体フロー

┌─────────────┐
│   ユーザー   │
└──────┬──────┘
       │ 質問（自然言語）
       ↓
┌─────────────────────────┐
│   Next.js API Route     │
│   /api/chat             │
└──────┬──────────────────┘
       │
       ↓
┌─────────────────────────┐
│   Vercel AI SDK         │
│   streamText()          │
└──────┬──────────────────┘
       │
       ↓
┌─────────────────────────┐
│   GA4 Dynamic Tools     │
│   createGA4Tools()      │
└──────┬──────────────────┘
       │
       ↓
┌─────────────────────────┐
│   MCP Client            │
│   getMCPClient()        │
└──────┬──────────────────┘
       │
       ↓
┌─────────────────────────┐
│   Stdio Transport       │
│   (pipx + Python MCP)   │
└──────┬──────────────────┘
       │
       ↓
┌─────────────────────────┐
│   Google Analytics      │
│   Data API v1           │
└─────────────────────────┘

MCP Client 実装の詳細解説

1. MCP クライアントの初期化

// lib/mcp/client.ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

let mcpClient: Client | null = null;

export async function getMCPClient(): Promise<Client | null> {
  // シングルトンパターンで既存のクライアントを再利用
  if (mcpClient) {
    return mcpClient;
  }

  // Google Cloud認証情報のパスを環境変数から取得
  const credentialsPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;

  if (!credentialsPath) {
    console.warn(
      "GOOGLE_APPLICATION_CREDENTIALS is not set. GA4 MCP tools will not be available."
    );
    return null;
  }

  try {
    // Stdio Transportの設定
    const transport = new StdioClientTransport({
      command: "pipx",
      args: [
        "run",
        "--spec",
        "git+https://github.com/googleanalytics/google-analytics-mcp.git",
        "google-analytics-mcp",
      ],
      env: {
        ...process.env,
        GOOGLE_APPLICATION_CREDENTIALS: credentialsPath,
      },
    });

    // MCPクライアントの作成
    const client = new Client(
      {
        name: "analytics-mcp-ai-chatbot",
        version: "1.0.0",
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );

    // トランスポートに接続
    await client.connect(transport);

    mcpClient = client;
    return client;
  } catch (error) {
    console.error("Failed to connect to GA4 MCP server:", error);
    return null;
  }
}

実装のポイント

シングルトンパターン

MCP クライアントは初回作成後、グローバル変数に保存
複数リクエストで同一クライアントを再利用し、接続コストを削減

Stdio Transport

pipx runを使用して Python 製の GA4 MCP サーバーをオンデマンドで起動
GitHub リポジトリから直接実行するため、事前インストール不要
環境変数GOOGLE_APPLICATION_CREDENTIALSを子プロセスに渡す

エラーハンドリング

認証情報が未設定の場合は警告を出してnullを返す
接続失敗時もアプリケーション全体は継続動作

2. MCP ツールの一覧取得

export async function listMCPTools() {
  const client = await getMCPClient();
  if (!client) {
    return [];
  }

  try {
    const response = await client.listTools();
    return response.tools || [];
  } catch (error) {
    console.error("Failed to list MCP tools:", error);
    return [];
  }
}

MCP サーバーが提供するツールの一覧を取得します。GA4 MCP サーバーは以下のようなツールを提供します：

run_report: カスタムレポートの実行
get_realtime_report: リアルタイムレポートの取得
get_metadata: 利用可能なディメンションとメトリクスの一覧取得

3. MCP ツールの実行

export async function callMCPTool(name: string, args: Record<string, unknown>) {
  const client = await getMCPClient();
  if (!client) {
    throw new Error("MCP client is not available");
  }

  try {
    const response = await client.callTool({
      name,
      arguments: args,
    });
    return response;
  } catch (error) {
    console.error(`Failed to call MCP tool ${name}:`, error);
    throw error;
  }
}

指定されたツール名とパラメータで MCP ツールを呼び出します。

Dynamic Tool Creation：AI ツールへの動的変換

MCP ツールを Vercel AI SDK のツール形式に動的に変換する仕組みが、このシステムの核心部分です。

// lib/ai/tools/ga4-analytics.ts
import { tool } from "ai";
import { z } from "zod";
import { callMCPTool, listMCPTools } from "@/lib/mcp/client";

let availableTools: Array<{
  name: string;
  description?: string;
  inputSchema?: z.ZodTypeAny;
}> = [];

async function initializeTools() {
  if (availableTools.length === 0) {
    // MCPツール一覧を取得
    const tools = await listMCPTools();

    // Zodスキーマに変換
    availableTools = tools.map((t) => ({
      name: t.name,
      description: t.description || "",
      inputSchema: t.inputSchema
        ? convertJSONSchemaToZod(t.inputSchema)
        : undefined,
    }));
  }
  return availableTools;
}

JSON Schema → Zod スキーマ変換

MCP ツールのパラメータは JSON Schema で定義されています。これを Zod スキーマに変換することで、型安全性を確保します。

function convertJSONSchemaToZod(schema: unknown): z.ZodTypeAny | undefined {
  if (typeof schema === "object" && schema !== null) {
    const jsonSchema = schema as Record<string, unknown>;
    if (jsonSchema.type === "object" && jsonSchema.properties) {
      const shape: Record<string, z.ZodTypeAny> = {};
      const properties = jsonSchema.properties as Record<
        string,
        Record<string, unknown>
      >;

      for (const [key, prop] of Object.entries(properties)) {
        if (prop.type === "string") {
          shape[key] = z.string().optional();
        } else if (prop.type === "number" || prop.type === "integer") {
          shape[key] = z.number().optional();
        } else if (prop.type === "boolean") {
          shape[key] = z.boolean().optional();
        } else if (prop.type === "array") {
          shape[key] = z.array(z.unknown()).optional();
        } else {
          shape[key] = z.unknown().optional();
        }
      }
      return z.object(shape);
    }
  }
  return z.record(z.unknown()).optional();
}

AI SDK ツールの動的生成

export async function createGA4Tools() {
  const tools = await initializeTools();

  if (tools.length === 0) {
    return {};
  }

  const toolMap: Record<string, any> = {};

  for (const toolInfo of tools) {
    toolMap[toolInfo.name] = tool({
      description:
        toolInfo.description ||
        `GA4 Analytics tool: ${toolInfo.name}. Use this to query Google Analytics 4 data.`,
      inputSchema: z.record(z.string(), z.unknown()),
      execute: async (input: Record<string, unknown>) => {
        try {
          // MCPツールを実行
          const result = await callMCPTool(toolInfo.name, input);

          // レスポンスからテキストコンテンツを抽出
          if (Array.isArray(result.content)) {
            const textContent = result.content
              .filter((c) => c.type === "text")
              .map((c) => (c as { text: string }).text)
              .join("\n");
            return {
              success: true,
              content: textContent || JSON.stringify(result.content),
              isError: result.isError,
            };
          }
          return {
            success: true,
            content: JSON.stringify(result.content),
            isError: result.isError,
          };
        } catch (error) {
          return {
            success: false,
            error:
              error instanceof Error ? error.message : "Unknown error occurred",
          };
        }
      },
    });
  }

  return toolMap;
}

ポイント解説

動的ツール生成
- MCP サーバーが提供するツールを実行時に検出
- ハードコーディング不要で新しいツールに自動対応
統一的なレスポンス処理
- MCP レスポンスの content フィールドからテキストを抽出
- 成功/失敗を統一的なフォーマットで返却
エラーハンドリング
- ツール実行時のエラーをキャッチして適切に処理
- AI モデルがエラー内容を理解して対応可能

Chat API Route での統合

// app/(chat)/api/chat/route.ts
import { createGA4Tools } from "@/lib/ai/tools/ga4-analytics";

export async function POST(request: Request) {
  // ... 認証・セッション処理 ...

  // GA4ツールを動的にロード
  const ga4Tools = await createGA4Tools();
  const ga4ToolNames = Object.keys(ga4Tools);

  const stream = createUIMessageStream({
    execute: ({ writer: dataStream }) => {
      const baseTools = {
        ...ga4Tools, // MCPツールをマージ
      };

      const streamTextConfig: Parameters<typeof streamText>[0] = {
        model: myProvider.languageModel(selectedChatModel),
        system: systemPrompt({ selectedChatModel, requestHints, message }),
        messages: convertToModelMessages(uiMessages),
        tools: baseTools, // ツールを登録
        // ... その他の設定 ...
      };

      return streamText(streamTextConfig);
    },
  });

  return stream.toResponse();
}

処理フロー

ユーザーからチャットメッセージを受信
createGA4Tools()で利用可能な GA4 ツールを取得
Vercel AI SDK のstreamText()にツールを渡す
AI モデルが必要に応じてツールを呼び出し
結果をストリーミングレスポンスで返却

System Prompt 設計

AI モデルが GA4 データを適切に活用するために、詳細なシステムプロンプトを設定しています。

// lib/ai/prompts.ts
export const regularPrompt = `
#役割
あなたはwebサイトのアクセス解析のエキスパートです。

#目的
ユーザーの質問に対して、Googleアナリティクス4(GA4)データを活用して、的確で実用的な回答を提供します。

#制約条件
- 回答は日本語で行ってください。
- ユーザーの質問に対して、GA4データを基にした具体的な洞察や提案を提供してください。
- 必要に応じて、GA4の指標やディメンションを引用してください。
- プロパティIDはサイト名に変換して表示してください。
- グラフを基にこのサイトの概況を解説してください。

#グラフの表示方法
データをビジュアル化する際は、以下のJSON形式でチャート設定を記述してください。
システムが自動的にグラフとして表示します。

**フォーマット:**
\`\`\`json
{
  "type": "bar",
  "data": {
    "labels": ["A", "B"],
    "datasets": [{
      "label": "データ名",
      "data": [10, 20],
      "backgroundColor": "rgba(54, 162, 235, 0.6)"
    }]
  },
  "options": {
    "plugins": {
      "title": {
        "display": true,
        "text": "グラフタイトル"
      }
    }
  }
}
\`\`\`
`;

export const systemPrompt = ({
  selectedChatModel,
  requestHints,
  message,
}: {
  selectedChatModel: string;
  requestHints: RequestHints;
  message: ChatMessage;
}) => {
  const ga4PropertiesPrompt = getGA4PropertiesPrompt(
    requestHints.selectedProperties
  );

  return `${regularPrompt}\n\n${ga4PropertiesPrompt}`;
};

プロンプト設計のポイント

役割の明確化：アクセス解析エキスパートとして振る舞う
出力フォーマット指定：Chart.js JSON フォーマットでグラフを生成
選択プロパティの注入：ユーザーが選択した GA4 プロパティ ID を動的に追加
日本語出力の強制：ユーザーインターフェースの統一性を確保

認証とセキュリティ

Google Cloud 認証

# サービスアカウントJSON鍵ファイルのパスを環境変数に設定
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

セキュリティ対策

サーバーサイド実行：MCP クライアントはサーバーサイドでのみ実行
認証情報の保護：環境変数による管理、リポジトリにコミットしない
ユーザー認証：Auth.js によるセッション管理
プロパティアクセス制御：ユーザーが選択したプロパティのみアクセス可能

デプロイメント

Vercel へのデプロイ

環境変数の設定

GOOGLE_APPLICATION_CREDENTIALS=/tmp/gcp-credentials.json

Build 設定

{
  "scripts": {
    "build": "tsx lib/db/migrate && next build"
  }
}

pipx の利用可能性
- Vercel 環境では pipx が標準で利用可能
- Python MCP サーバーを動的に実行できる

パフォーマンス最適化

1. MCP クライアントのキャッシング

let mcpClient: Client | null = null; // グローバル変数でキャッシュ

2. ツール情報のメモ化

let availableTools: Array<...> = []; // 初回取得後は再利用

3. ストリーミングレスポンス

const stream = createUIMessageStream({
  execute: ({ writer: dataStream }) => {
    return streamText(streamTextConfig);
  },
});

AI の応答をストリーミングで返すことで、ユーザー体験を向上。

実際の使用例

ユーザーの質問

「先月のセッション数を教えてください」

システムの動作

AI モデルが質問を解析
適切な GA4 ツール（例：run_report）を選択

パラメータを生成：

{
  "property_id": "properties/123456789",
  "metrics": ["sessions"],
  "date_ranges": [{ "start_date": "30daysAgo", "end_date": "yesterday" }]
}

MCP クライアントがツールを実行
GA4 Data API からデータを取得
結果を日本語で整形して返答

AI の応答例

先月（過去30日間）のセッション数は1,234件でした。

前月比で+15.2%の増加となっており、順調に成長しています。
特にオーガニック検索からの流入が全体の45%を占めています。

トラブルシューティング

よくある問題と解決策

1. MCP 接続失敗

Failed to connect to GA4 MCP server

原因：GOOGLE_APPLICATION_CREDENTIALSが未設定
解決：環境変数を正しく設定する

2. pipx not found

command not found: pipx

原因：pipx がインストールされていない
解決：pip install pipxでインストール

3. 認証エラー

Permission denied on GA4 property

原因：サービスアカウントに権限がない
解決：GA4 プロパティでサービスアカウントに「閲覧者」権限を付与

まとめ

本記事では、Google Analytics MCP を活用した自然言語分析サービスの実装について解説しました。

主要なポイント

MCP SDK：標準化されたプロトコルで外部ツールと連携
Dynamic Tool Creation：MCP ツールを AI SDK ツールに動的変換
Stdio Transport：pipx で Python MCP サーバーをオンデマンド実行
型安全性：JSON Schema → Zod 変換による型チェック
セキュリティ：サーバーサイド実行と適切な認証管理

今後の拡張可能性

他の MCP サーバーとの連携（例：Search Console、BigQuery）
カスタム MCP ツールの追加
マルチモーダル分析（画像・動画データの分析）
リアルタイムアラート機能

MCP プロトコルの活用により、柔軟で拡張性の高い AI 分析サービスを構築できることがお分かりいただけたかと思います。

参考リンク