@dongsik/ga4-mcp 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# ga4-mcp
+
+[한국어](docs/README.ko.md)
+
+An MCP server for querying and analyzing Google Analytics 4 data directly from Claude Desktop.
+
+## Features
+
+### Basic Queries
+| Tool | Description |
+|---|---|
+| `list_accounts` | List GA4 accounts |
+| `list_properties` | List properties within an account |
+| `run_report` | Run custom reports with flexible metric/dimension combinations and dimension filters |
+
+### Page & Traffic Analysis
+| Tool | Description |
+|---|---|
+| `get_top_pages` | Top pages by pageviews, sessions, avg. duration, bounce rate |
+| `get_traffic_sources` | Traffic source breakdown by source/medium |
+
+### User Analysis
+| Tool | Description |
+|---|---|
+| `get_user_overview` | User overview (total users, new users, sessions, pageviews, etc.) |
+| `get_users_by_country` | Users by country |
+| `get_users_by_device` | Users by device category (desktop, mobile, tablet) |
+
+### Trends & Realtime
+| Tool | Description |
+|---|---|
+| `get_trend_by_date` | Daily trends (pageviews, sessions, users over time) |
+| `get_realtime` | Realtime active users and pageviews |
+
+### Campaign Analysis
+| Tool | Description |
+|---|---|
+| `get_campaign_performance` | Campaign performance (sessions, users, conversions, bounce rate). Filter by campaign name |
+| `get_utm_breakdown` | Full UTM parameter analysis (campaign, source, medium, content, keyword) |
+| `compare_campaigns` | Compare performance across multiple campaigns |
+
+### Metadata
+| Tool | Description |
+|---|---|
+| `get_metadata` | List all available metrics and dimensions |
+| `search_metadata` | Search metrics/dimensions by keyword |
+| `list_categories` | List metric/dimension categories |
+
+## Prerequisites
+
+### Google Cloud Console Setup
+
+1. Create or select a project in [Google Cloud Console](https://console.cloud.google.com/)
+2. **APIs & Services → Library** → Enable "Google Analytics Data API"
+3. **APIs & Services → Library** → Enable "Google Analytics Admin API"
+4. **APIs & Services → Credentials** → Create **OAuth 2.0 Client ID** (type: Desktop app)
+5. Download the JSON file and save as `client_secret.json`
+
+## Installation
+
+### Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ga": {
+      "command": "npx",
+      "args": ["-y", "ga4-mcp"],
+      "env": {
+        "GA_CLIENT_SECRET_PATH": "/path/to/client_secret.json",
+        "GA4_PROPERTY_ID": "123456789"
+      }
+    }
+  }
+}
+```
+
+> Windows path example: `"C:\\Users\\username\\client_secret.json"`
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GA_CLIENT_SECRET_PATH` | Yes | Path to OAuth client_secret.json file |
+| `GA4_PROPERTY_ID` | No | Default GA4 property ID. When set, you don't need to specify propertyId for each request |
+
+### First Run
+
+On first launch, a browser window will open for Google OAuth login. After authentication, the token is saved locally and subsequent requests will authenticate automatically.
+
+## Usage Examples
+
+Ask questions in natural language through Claude Desktop:
+
+- "Show me the top pages for the last 30 days"
+- "Analyze traffic sources for this month"
+- "Compare users this week vs last week"
+- "Show user distribution by country"
+- "How many users are online right now?"
+- "Show performance for the spring_sale campaign"
+- "Break down traffic by UTM parameters"
+- "Compare campaign A vs campaign B"
+- "What campaign-related dimensions are available in GA4?"
+
+## Dimension Filters
+
+Use dimension filters in `run_report` to narrow down results:
+
+```
+"Show only pages starting with /blog for the last 30 days"
+→ dimensionFilter: { fieldName: "pagePath", matchType: "BEGINS_WITH", value: "/blog" }
+
+"Analyze only traffic from google"
+→ dimensionFilter: { fieldName: "sessionSource", matchType: "EXACT", value: "google" }
+```
+
+Supported match types: `EXACT`, `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, `REGEXP`
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+import { OAuth2Client } from "google-auth-library";
+export declare function getAuthenticatedClient(clientSecretPath: string): Promise<OAuth2Client>;

package/dist/auth.js

@@ -0,0 +1,104 @@
+import { google } from "googleapis";
+import * as fs from "fs";
+import * as path from "path";
+import * as http from "http";
+import open from "open";
+const SCOPES = [
+    "https://www.googleapis.com/auth/analytics.readonly",
+];
+const TOKEN_DIR = path.join(process.env.HOME || process.env.USERPROFILE || ".", ".ga-mcp");
+const TOKEN_PATH = path.join(TOKEN_DIR, "token.json");
+function loadClientCredentials(clientSecretPath) {
+    const content = fs.readFileSync(clientSecretPath, "utf-8");
+    const json = JSON.parse(content);
+    // Google Cloud Console exports as { installed: {...} } or { web: {...} }
+    const creds = json.installed || json.web;
+    if (!creds) {
+        throw new Error("client_secret.json must contain 'installed' or 'web' credentials");
+    }
+    return creds;
+}
+function loadSavedToken() {
+    try {
+        const content = fs.readFileSync(TOKEN_PATH, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function saveToken(token) {
+    if (!fs.existsSync(TOKEN_DIR)) {
+        fs.mkdirSync(TOKEN_DIR, { recursive: true });
+    }
+    fs.writeFileSync(TOKEN_PATH, JSON.stringify(token, null, 2));
+}
+async function authorizeViaLocalServer(oauth2Client) {
+    const authUrl = oauth2Client.generateAuthUrl({
+        access_type: "offline",
+        scope: SCOPES,
+        prompt: "consent",
+    });
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(async (req, res) => {
+            try {
+                const url = new URL(req.url, `http://localhost:3000`);
+                const code = url.searchParams.get("code");
+                if (!code) {
+                    res.writeHead(400);
+                    res.end("No authorization code received");
+                    return;
+                }
+                const { tokens } = await oauth2Client.getToken(code);
+                oauth2Client.setCredentials(tokens);
+                saveToken(tokens);
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>인증 완료!</h1><p>이 창을 닫아도 됩니다.</p><script>window.close()</script>");
+                server.close();
+                resolve();
+            }
+            catch (err) {
+                res.writeHead(500);
+                res.end("Authentication failed");
+                server.close();
+                reject(err);
+            }
+        });
+        server.listen(3000, () => {
+            open(authUrl).catch(() => {
+                console.error(`Open this URL in your browser:\n${authUrl}`);
+            });
+        });
+        // Timeout after 2 minutes
+        setTimeout(() => {
+            server.close();
+            reject(new Error("Authentication timed out"));
+        }, 120000);
+    });
+}
+export async function getAuthenticatedClient(clientSecretPath) {
+    const creds = loadClientCredentials(clientSecretPath);
+    const oauth2Client = new google.auth.OAuth2(creds.client_id, creds.client_secret, "http://localhost:3000");
+    // Try to use saved token
+    const savedToken = loadSavedToken();
+    if (savedToken) {
+        oauth2Client.setCredentials(savedToken);
+        // Refresh if expired
+        if (savedToken.expiry_date &&
+            savedToken.expiry_date < Date.now()) {
+            try {
+                const { credentials } = await oauth2Client.refreshAccessToken();
+                oauth2Client.setCredentials(credentials);
+                saveToken(credentials);
+            }
+            catch {
+                // Token refresh failed, need to re-auth
+                await authorizeViaLocalServer(oauth2Client);
+            }
+        }
+        return oauth2Client;
+    }
+    // No saved token, start OAuth flow
+    await authorizeViaLocalServer(oauth2Client);
+    return oauth2Client;
+}

package/dist/ga.d.ts

@@ -0,0 +1,114 @@
+import { OAuth2Client } from "google-auth-library";
+export interface DimensionFilter {
+    fieldName: string;
+    matchType: "EXACT" | "BEGINS_WITH" | "ENDS_WITH" | "CONTAINS" | "REGEXP";
+    value: string;
+    caseSensitive?: boolean;
+}
+export declare class GA4Client {
+    private analyticsData;
+    private analyticsAdmin;
+    constructor(auth: OAuth2Client);
+    listAccounts(): Promise<{
+        name: string | null | undefined;
+        displayName: string | null | undefined;
+    }[]>;
+    listProperties(accountId: string): Promise<{
+        name: string | null | undefined;
+        displayName: string | null | undefined;
+        propertyId: string | undefined;
+    }[]>;
+    runReport(params: {
+        propertyId: string;
+        startDate: string;
+        endDate: string;
+        metrics: string[];
+        dimensions?: string[];
+        dimensionFilters?: DimensionFilter[];
+        limit?: number;
+        orderBy?: string;
+        orderDesc?: boolean;
+    }): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getTopPages(propertyId: string, startDate: string, endDate: string, limit?: number): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getTrafficSources(propertyId: string, startDate: string, endDate: string, limit?: number): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getUserOverview(propertyId: string, startDate: string, endDate: string): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getUsersByCountry(propertyId: string, startDate: string, endDate: string, limit?: number): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getUsersByDevice(propertyId: string, startDate: string, endDate: string): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getPagesByDate(propertyId: string, startDate: string, endDate: string): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getRealtimeReport(propertyId: string): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getCampaignPerformance(propertyId: string, startDate: string, endDate: string, limit?: number, campaignName?: string): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getUtmBreakdown(propertyId: string, startDate: string, endDate: string, limit?: number): Promise<{
+        headers: string[];
+        rows: Record<string, string>[];
+        rowCount: number;
+        totals: any;
+    }>;
+    getCampaignComparison(propertyId: string, startDate: string, endDate: string, campaignNames: string[]): Promise<Record<string, any>>;
+    getMetadata(propertyId: string): Promise<{
+        dimensions: {
+            apiName: string | null | undefined;
+            uiName: string | null | undefined;
+            category: string | null | undefined;
+            description: string | null | undefined;
+        }[];
+        metrics: {
+            apiName: string | null | undefined;
+            uiName: string | null | undefined;
+            category: string | null | undefined;
+            description: string | null | undefined;
+            type: string | null | undefined;
+        }[];
+    }>;
+    searchMetadata(propertyId: string, keyword: string, type?: "dimensions" | "metrics"): Promise<any>;
+    listCategories(propertyId: string): Promise<{
+        dimensionCategories: (string | null | undefined)[];
+        metricCategories: (string | null | undefined)[];
+    }>;
+    private buildDimensionFilter;
+    private formatReportResponse;
+}

package/dist/ga.js

@@ -0,0 +1,310 @@
+import { google } from "googleapis";
+export class GA4Client {
+    analyticsData;
+    analyticsAdmin;
+    constructor(auth) {
+        this.analyticsData = google.analyticsdata({ version: "v1beta", auth });
+        this.analyticsAdmin = google.analyticsadmin({ version: "v1beta", auth });
+    }
+    async listAccounts() {
+        const res = await this.analyticsAdmin.accounts.list();
+        return (res.data.accounts || []).map((a) => ({
+            name: a.name,
+            displayName: a.displayName,
+        }));
+    }
+    async listProperties(accountId) {
+        const res = await this.analyticsAdmin.properties.list({
+            filter: `parent:accounts/${accountId}`,
+        });
+        return (res.data.properties || []).map((p) => ({
+            name: p.name,
+            displayName: p.displayName,
+            propertyId: p.name?.replace("properties/", ""),
+        }));
+    }
+    async runReport(params) {
+        const request = {
+            dateRanges: [{ startDate: params.startDate, endDate: params.endDate }],
+            metrics: params.metrics.map((m) => ({ name: m })),
+            limit: String(params.limit || 100),
+        };
+        if (params.dimensions?.length) {
+            request.dimensions = params.dimensions.map((d) => ({ name: d }));
+        }
+        if (params.dimensionFilters?.length) {
+            request.dimensionFilter = this.buildDimensionFilter(params.dimensionFilters);
+        }
+        if (params.orderBy) {
+            const isMetric = params.metrics.includes(params.orderBy);
+            request.orderBys = [
+                {
+                    desc: params.orderDesc ?? true,
+                    ...(isMetric
+                        ? { metric: { metricName: params.orderBy } }
+                        : { dimension: { dimensionName: params.orderBy } }),
+                },
+            ];
+        }
+        const res = await this.analyticsData.properties.runReport({
+            property: `properties/${params.propertyId}`,
+            requestBody: request,
+        });
+        return this.formatReportResponse(res.data);
+    }
+    // --- 편의 도구들 ---
+    async getTopPages(propertyId, startDate, endDate, limit = 20) {
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: ["screenPageViews", "sessions", "averageSessionDuration", "bounceRate"],
+            dimensions: ["pagePath", "pageTitle"],
+            limit,
+            orderBy: "screenPageViews",
+        });
+    }
+    async getTrafficSources(propertyId, startDate, endDate, limit = 20) {
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: ["sessions", "totalUsers", "newUsers", "bounceRate"],
+            dimensions: ["sessionSource", "sessionMedium"],
+            limit,
+            orderBy: "sessions",
+        });
+    }
+    async getUserOverview(propertyId, startDate, endDate) {
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: [
+                "totalUsers",
+                "newUsers",
+                "sessions",
+                "screenPageViews",
+                "averageSessionDuration",
+                "bounceRate",
+                "sessionsPerUser",
+            ],
+        });
+    }
+    async getUsersByCountry(propertyId, startDate, endDate, limit = 20) {
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: ["totalUsers", "sessions", "screenPageViews"],
+            dimensions: ["country"],
+            limit,
+            orderBy: "totalUsers",
+        });
+    }
+    async getUsersByDevice(propertyId, startDate, endDate) {
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: ["totalUsers", "sessions", "screenPageViews", "averageSessionDuration"],
+            dimensions: ["deviceCategory"],
+            orderBy: "totalUsers",
+        });
+    }
+    async getPagesByDate(propertyId, startDate, endDate) {
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: ["screenPageViews", "sessions", "totalUsers"],
+            dimensions: ["date"],
+            orderBy: "date",
+            orderDesc: false,
+        });
+    }
+    async getRealtimeReport(propertyId) {
+        const res = await this.analyticsData.properties.runRealtimeReport({
+            property: `properties/${propertyId}`,
+            requestBody: {
+                metrics: [
+                    { name: "activeUsers" },
+                    { name: "screenPageViews" },
+                ],
+                dimensions: [
+                    { name: "pagePath" },
+                ],
+                limit: "20",
+            },
+        });
+        return this.formatReportResponse(res.data);
+    }
+    // --- 캠페인 분석 ---
+    async getCampaignPerformance(propertyId, startDate, endDate, limit = 20, campaignName) {
+        const filters = [];
+        if (campaignName) {
+            filters.push({
+                fieldName: "sessionCampaignName",
+                matchType: "CONTAINS",
+                value: campaignName,
+            });
+        }
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: [
+                "sessions",
+                "totalUsers",
+                "newUsers",
+                "screenPageViews",
+                "averageSessionDuration",
+                "bounceRate",
+                "conversions",
+            ],
+            dimensions: ["sessionCampaignName", "sessionSource", "sessionMedium"],
+            dimensionFilters: filters.length ? filters : undefined,
+            limit,
+            orderBy: "sessions",
+        });
+    }
+    async getUtmBreakdown(propertyId, startDate, endDate, limit = 30) {
+        return this.runReport({
+            propertyId,
+            startDate,
+            endDate,
+            metrics: ["sessions", "totalUsers", "newUsers", "bounceRate", "conversions"],
+            dimensions: [
+                "sessionCampaignName",
+                "sessionSource",
+                "sessionMedium",
+                "sessionManualAdContent",
+                "sessionGoogleAdsKeyword",
+            ],
+            limit,
+            orderBy: "sessions",
+        });
+    }
+    async getCampaignComparison(propertyId, startDate, endDate, campaignNames) {
+        const results = {};
+        for (const name of campaignNames) {
+            results[name] = await this.runReport({
+                propertyId,
+                startDate,
+                endDate,
+                metrics: [
+                    "sessions",
+                    "totalUsers",
+                    "newUsers",
+                    "screenPageViews",
+                    "averageSessionDuration",
+                    "bounceRate",
+                    "conversions",
+                ],
+                dimensions: ["sessionCampaignName"],
+                dimensionFilters: [
+                    {
+                        fieldName: "sessionCampaignName",
+                        matchType: "EXACT",
+                        value: name,
+                    },
+                ],
+            });
+        }
+        return results;
+    }
+    // --- 메타데이터 ---
+    async getMetadata(propertyId) {
+        const res = await this.analyticsData.properties.getMetadata({
+            name: `properties/${propertyId}/metadata`,
+        });
+        const dimensions = (res.data.dimensions || []).map((d) => ({
+            apiName: d.apiName,
+            uiName: d.uiName,
+            category: d.category,
+            description: d.description,
+        }));
+        const metrics = (res.data.metrics || []).map((m) => ({
+            apiName: m.apiName,
+            uiName: m.uiName,
+            category: m.category,
+            description: m.description,
+            type: m.type,
+        }));
+        return { dimensions, metrics };
+    }
+    async searchMetadata(propertyId, keyword, type) {
+        const metadata = await this.getMetadata(propertyId);
+        const lower = keyword.toLowerCase();
+        const matchField = (item) => (item.apiName?.toLowerCase().includes(lower)) ||
+            (item.uiName?.toLowerCase().includes(lower)) ||
+            (item.description?.toLowerCase().includes(lower)) ||
+            (item.category?.toLowerCase().includes(lower));
+        const result = {};
+        if (!type || type === "dimensions") {
+            result.dimensions = metadata.dimensions.filter(matchField);
+        }
+        if (!type || type === "metrics") {
+            result.metrics = metadata.metrics.filter(matchField);
+        }
+        return result;
+    }
+    async listCategories(propertyId) {
+        const metadata = await this.getMetadata(propertyId);
+        const dimCategories = [...new Set(metadata.dimensions.map((d) => d.category).filter(Boolean))];
+        const metricCategories = [...new Set(metadata.metrics.map((m) => m.category).filter(Boolean))];
+        return {
+            dimensionCategories: dimCategories,
+            metricCategories: metricCategories,
+        };
+    }
+    // --- 내부 유틸 ---
+    buildDimensionFilter(filters) {
+        if (filters.length === 1) {
+            return {
+                filter: {
+                    fieldName: filters[0].fieldName,
+                    stringFilter: {
+                        matchType: filters[0].matchType,
+                        value: filters[0].value,
+                        caseSensitive: filters[0].caseSensitive ?? false,
+                    },
+                },
+            };
+        }
+        return {
+            andGroup: {
+                expressions: filters.map((f) => ({
+                    filter: {
+                        fieldName: f.fieldName,
+                        stringFilter: {
+                            matchType: f.matchType,
+                            value: f.value,
+                            caseSensitive: f.caseSensitive ?? false,
+                        },
+                    },
+                })),
+            },
+        };
+    }
+    formatReportResponse(data) {
+        const dimensionHeaders = (data.dimensionHeaders || []).map((h) => h.name || "unknown");
+        const metricHeaders = (data.metricHeaders || []).map((h) => h.name || "unknown");
+        const rows = (data.rows || []).map((row) => {
+            const obj = {};
+            (row.dimensionValues || []).forEach((v, i) => {
+                obj[dimensionHeaders[i]] = v.value || "";
+            });
+            (row.metricValues || []).forEach((v, i) => {
+                obj[metricHeaders[i]] = v.value || "";
+            });
+            return obj;
+        });
+        return {
+            headers: [...dimensionHeaders, ...metricHeaders],
+            rows,
+            rowCount: data.rowCount || 0,
+            totals: data.totals,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+declare function main(): Promise<void>;
+export { main };

package/dist/index.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getAuthenticatedClient } from "./auth.js";
+import { GA4Client } from "./ga.js";
+const CLIENT_SECRET_PATH = process.env.GA_CLIENT_SECRET_PATH ||
+    new URL("../client_secret.json", import.meta.url).pathname;
+const DEFAULT_PROPERTY_ID = process.env.GA4_PROPERTY_ID || "";
+let ga4 = null;
+async function getGA4() {
+    if (!ga4) {
+        const auth = await getAuthenticatedClient(CLIENT_SECRET_PATH);
+        ga4 = new GA4Client(auth);
+    }
+    return ga4;
+}
+function resolvePropertyId(propertyId) {
+    const id = propertyId || DEFAULT_PROPERTY_ID;
+    if (!id) {
+        throw new Error("propertyId is required. Pass it as a parameter or set the GA4_PROPERTY_ID environment variable.");
+    }
+    return id;
+}
+const server = new McpServer({
+    name: "ga4-mcp",
+    version: "0.2.0",
+});
+const propertyIdSchema = DEFAULT_PROPERTY_ID
+    ? z.string().optional().describe("GA4 property ID (uses GA4_PROPERTY_ID env var if omitted)")
+    : z.string().describe("GA4 property ID (numeric)");
+const dimensionFilterSchema = z
+    .array(z.object({
+    fieldName: z.string().describe("Dimension to filter (e.g. pagePath, sessionCampaignName)"),
+    matchType: z
+        .enum(["EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "REGEXP"])
+        .describe("Match type"),
+    value: z.string().describe("Filter value"),
+    caseSensitive: z.boolean().optional().describe("Case sensitive (default false)"),
+}))
+    .optional()
+    .describe("Dimension filters");
+// --- Basic ---
+server.tool("list_accounts", "List all GA4 accounts", {}, async () => {
+    const client = await getGA4();
+    const accounts = await client.listAccounts();
+    return {
+        content: [{ type: "text", text: JSON.stringify(accounts, null, 2) }],
+    };
+});
+server.tool("list_properties", "List GA4 properties for a given account", { accountId: z.string().describe("GA4 account ID (numeric)") }, async ({ accountId }) => {
+    const client = await getGA4();
+    const properties = await client.listProperties(accountId);
+    return {
+        content: [{ type: "text", text: JSON.stringify(properties, null, 2) }],
+    };
+});
+server.tool("run_report", "Run a custom GA4 report with flexible metric/dimension combinations and dimension filters", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date (YYYY-MM-DD or relative like 7daysAgo, 30daysAgo)"),
+    endDate: z.string().describe("End date (YYYY-MM-DD or relative like today, yesterday)"),
+    metrics: z
+        .array(z.string())
+        .describe("Metrics (e.g. totalUsers, sessions, screenPageViews, bounceRate, averageSessionDuration, conversions)"),
+    dimensions: z
+        .array(z.string())
+        .optional()
+        .describe("Dimensions (e.g. pagePath, pageTitle, sessionSource, sessionMedium, sessionCampaignName, country, city, date, deviceCategory)"),
+    dimensionFilters: dimensionFilterSchema,
+    limit: z.number().optional().describe("Max rows (default 100)"),
+    orderBy: z.string().optional().describe("Field to sort by"),
+    orderDesc: z.boolean().optional().describe("Sort descending (default true)"),
+}, async (params) => {
+    const client = await getGA4();
+    const result = await client.runReport({
+        ...params,
+        propertyId: resolvePropertyId(params.propertyId),
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// --- Page & Traffic ---
+server.tool("get_top_pages", "Get top pages by pageviews, sessions, avg. duration, and bounce rate", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+    limit: z.number().optional().describe("Max rows (default 20)"),
+}, async ({ propertyId, startDate, endDate, limit }) => {
+    const client = await getGA4();
+    const result = await client.getTopPages(resolvePropertyId(propertyId), startDate, endDate, limit);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("get_traffic_sources", "Analyze traffic sources by source/medium with sessions, users, and bounce rate", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+    limit: z.number().optional().describe("Max rows (default 20)"),
+}, async ({ propertyId, startDate, endDate, limit }) => {
+    const client = await getGA4();
+    const result = await client.getTrafficSources(resolvePropertyId(propertyId), startDate, endDate, limit);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// --- User Analysis ---
+server.tool("get_user_overview", "User overview: total users, new users, sessions, pageviews, avg. duration, bounce rate", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+}, async ({ propertyId, startDate, endDate }) => {
+    const client = await getGA4();
+    const result = await client.getUserOverview(resolvePropertyId(propertyId), startDate, endDate);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("get_users_by_country", "Analyze users by country", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+    limit: z.number().optional().describe("Max rows (default 20)"),
+}, async ({ propertyId, startDate, endDate, limit }) => {
+    const client = await getGA4();
+    const result = await client.getUsersByCountry(resolvePropertyId(propertyId), startDate, endDate, limit);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("get_users_by_device", "Analyze users by device category (desktop, mobile, tablet)", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+}, async ({ propertyId, startDate, endDate }) => {
+    const client = await getGA4();
+    const result = await client.getUsersByDevice(resolvePropertyId(propertyId), startDate, endDate);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// --- Trends & Realtime ---
+server.tool("get_trend_by_date", "Daily trend analysis: pageviews, sessions, and users over time", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+}, async ({ propertyId, startDate, endDate }) => {
+    const client = await getGA4();
+    const result = await client.getPagesByDate(resolvePropertyId(propertyId), startDate, endDate);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("get_realtime", "Get realtime active users and pageviews", {
+    propertyId: propertyIdSchema,
+}, async ({ propertyId }) => {
+    const client = await getGA4();
+    const result = await client.getRealtimeReport(resolvePropertyId(propertyId));
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// --- Campaign Analysis ---
+server.tool("get_campaign_performance", "Campaign performance: sessions, users, conversions, bounce rate per campaign. Supports filtering by campaign name", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+    campaignName: z.string().optional().describe("Filter by campaign name (partial match)"),
+    limit: z.number().optional().describe("Max rows (default 20)"),
+}, async ({ propertyId, startDate, endDate, campaignName, limit }) => {
+    const client = await getGA4();
+    const result = await client.getCampaignPerformance(resolvePropertyId(propertyId), startDate, endDate, limit, campaignName);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("get_utm_breakdown", "Full UTM parameter breakdown: campaign, source, medium, content, keyword", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+    limit: z.number().optional().describe("Max rows (default 30)"),
+}, async ({ propertyId, startDate, endDate, limit }) => {
+    const client = await getGA4();
+    const result = await client.getUtmBreakdown(resolvePropertyId(propertyId), startDate, endDate, limit);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("compare_campaigns", "Compare performance across multiple campaigns side by side", {
+    propertyId: propertyIdSchema,
+    startDate: z.string().describe("Start date"),
+    endDate: z.string().describe("End date"),
+    campaignNames: z
+        .array(z.string())
+        .describe("Campaign names to compare (exact match)"),
+}, async ({ propertyId, startDate, endDate, campaignNames }) => {
+    const client = await getGA4();
+    const result = await client.getCampaignComparison(resolvePropertyId(propertyId), startDate, endDate, campaignNames);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// --- Metadata ---
+server.tool("get_metadata", "List all available metrics and dimensions. Use this to discover what data you can query", {
+    propertyId: propertyIdSchema,
+    type: z.enum(["dimensions", "metrics", "both"]).optional().describe("Type to list (default both)"),
+}, async ({ propertyId, type }) => {
+    const client = await getGA4();
+    const metadata = await client.getMetadata(resolvePropertyId(propertyId));
+    const result = type === "dimensions"
+        ? { dimensions: metadata.dimensions }
+        : type === "metrics"
+            ? { metrics: metadata.metrics }
+            : metadata;
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("search_metadata", "Search metrics and dimensions by keyword (e.g. 'campaign', 'user', 'page')", {
+    propertyId: propertyIdSchema,
+    keyword: z.string().describe("Search keyword"),
+    type: z
+        .enum(["dimensions", "metrics"])
+        .optional()
+        .describe("Filter by type (searches all if omitted)"),
+}, async ({ propertyId, keyword, type }) => {
+    const client = await getGA4();
+    const result = await client.searchMetadata(resolvePropertyId(propertyId), keyword, type);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("list_categories", "List all metric and dimension categories", {
+    propertyId: propertyIdSchema,
+}, async ({ propertyId }) => {
+    const client = await getGA4();
+    const result = await client.listCategories(resolvePropertyId(propertyId));
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+export { main };

package/docs/README.ko.md

@@ -0,0 +1,122 @@
+# ga4-mcp
+
+Google Analytics 4 데이터를 Claude Desktop에서 바로 조회·분석할 수 있는 MCP 서버입니다.
+
+## 기능
+
+### 기본 조회
+| 도구 | 설명 |
+|---|---|
+| `list_accounts` | GA4 계정 목록 조회 |
+| `list_properties` | 계정 내 속성(Property) 목록 조회 |
+| `run_report` | 커스텀 리포트 실행 (메트릭/디멘션 자유 조합, 디멘션 필터 지원) |
+
+### 페이지/트래픽 분석
+| 도구 | 설명 |
+|---|---|
+| `get_top_pages` | 인기 페이지 (페이지뷰, 세션, 체류시간, 이탈률) |
+| `get_traffic_sources` | 트래픽 소스 분석 (소스/매체별) |
+
+### 사용자 분석
+| 도구 | 설명 |
+|---|---|
+| `get_user_overview` | 사용자 개요 (총 사용자, 신규, 세션, 페이지뷰 등) |
+| `get_users_by_country` | 국가별 사용자 분석 |
+| `get_users_by_device` | 기기별 사용자 분석 (desktop, mobile, tablet) |
+
+### 트렌드/실시간
+| 도구 | 설명 |
+|---|---|
+| `get_trend_by_date` | 일별 트렌드 (페이지뷰, 세션, 사용자 추이) |
+| `get_realtime` | 실시간 활성 사용자 및 페이지뷰 |
+
+### 캠페인 분석
+| 도구 | 설명 |
+|---|---|
+| `get_campaign_performance` | 캠페인 성과 분석 (세션, 사용자, 전환, 이탈률). 캠페인명 필터 가능 |
+| `get_utm_breakdown` | UTM 파라미터 전체 분석 (campaign, source, medium, content, keyword) |
+| `compare_campaigns` | 여러 캠페인 성과 비교 |
+
+### 메타데이터
+| 도구 | 설명 |
+|---|---|
+| `get_metadata` | 사용 가능한 모든 메트릭/디멘션 목록 조회 |
+| `search_metadata` | 키워드로 메트릭/디멘션 검색 |
+| `list_categories` | 메트릭/디멘션 카테고리 목록 |
+
+## 사전 준비
+
+### Google Cloud Console 설정
+
+1. [Google Cloud Console](https://console.cloud.google.com/)에서 프로젝트 생성 또는 선택
+2. **APIs & Services → Library** → "Google Analytics Data API" 활성화
+3. **APIs & Services → Library** → "Google Analytics Admin API" 활성화
+4. **APIs & Services → Credentials** → **OAuth 2.0 Client ID** 생성 (유형: Desktop app)
+5. JSON 다운로드 → `client_secret.json`으로 저장
+
+## 설치 및 실행
+
+### Claude Desktop 설정
+
+`claude_desktop_config.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "ga": {
+      "command": "npx",
+      "args": ["-y", "ga4-mcp"],
+      "env": {
+        "GA_CLIENT_SECRET_PATH": "/path/to/client_secret.json",
+        "GA4_PROPERTY_ID": "123456789"
+      }
+    }
+  }
+}
+```
+
+> Windows의 경우 경로 예시: `"C:\\Users\\사용자명\\client_secret.json"`
+
+### 환경변수
+
+| 변수 | 필수 | 설명 |
+|---|---|---|
+| `GA_CLIENT_SECRET_PATH` | 예 | OAuth client_secret.json 파일 경로 |
+| `GA4_PROPERTY_ID` | 아니오 | 기본 GA4 속성 ID. 설정하면 매번 propertyId를 입력하지 않아도 됨 |
+
+### 첫 실행
+
+Claude Desktop을 재시작하면 최초 1회 브라우저가 열리며 Google 로그인을 요청합니다.
+로그인 완료 후 토큰이 자동 저장되어 이후에는 별도 인증 없이 사용 가능합니다.
+
+## 사용 예시
+
+Claude Desktop에서 자연어로 질문하면 됩니다:
+
+- "우리 사이트 지난 30일 인기 페이지 보여줘"
+- "이번 달 트래픽 소스 분석해줘"
+- "지난주 대비 이번주 사용자 수 비교해줘"
+- "국가별 사용자 분포 알려줘"
+- "지금 실시간 접속자 몇 명이야?"
+- "spring_sale 캠페인 성과 보여줘"
+- "UTM 파라미터별 유입 현황 분석해줘"
+- "A캠페인이랑 B캠페인 성과 비교해줘"
+- "GA4에서 campaign 관련 디멘션 뭐가 있어?"
+
+## 디멘션 필터
+
+`run_report`에서 디멘션 필터를 사용하면 특정 조건의 데이터만 조회할 수 있습니다:
+
+```
+"지난 30일 /blog로 시작하는 페이지만 보여줘"
+→ dimensionFilter: { fieldName: "pagePath", matchType: "BEGINS_WITH", value: "/blog" }
+
+"google에서 유입된 트래픽만 분석해줘"
+→ dimensionFilter: { fieldName: "sessionSource", matchType: "EXACT", value: "google" }
+```
+
+지원하는 매칭 방식: `EXACT`, `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, `REGEXP`
+
+## 라이선스
+
+MIT

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@dongsik/ga4-mcp",
+  "version": "0.1.0",
+  "description": "Google Analytics 4 MCP Server",
+  "type": "module",
+  "bin": {
+    "ga-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "googleapis": "^144.0.0",
+    "open": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}