{"_id":"@dongsik/ga4-mcp","_rev":"4-69b32c3ea3a9aa731c96e7d14a0a3012","name":"@dongsik/ga4-mcp","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@dongsik/ga4-mcp","version":"0.1.0","_id":"@dongsik/ga4-mcp@0.1.0","maintainers":[{"name":"dongsik","email":"ehdtlr9376@gmail.com"}],"bin":{"ga-mcp":"dist/index.js"},"dist":{"shasum":"d92838a5635a1ca397c70dfa82f17abe8be19629","tarball":"https://registry.npmjs.org/@dongsik/ga4-mcp/-/ga4-mcp-0.1.0.tgz","fileCount":9,"integrity":"sha512-6huH9jrAg/VewkeFO0kl4NQOCNUKvGm5uGNIipJIW4Qc2ALs5p2mjUrK/CWYUBFqWVsR06nKaK5rNemB1BNOGw==","signatures":[{"sig":"MEUCIQCdZH4saa/tOatn2yh2GB9IGnKOVbQuZ8Vs+xBDvqsVpAIgBePj0yIMGYy3aTcViXwQx/V1Up/EceGLels/xLNki+8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38983},"type":"module","gitHead":"06e4b6287e24c5fb20f3a1229a6fb6c89dd0b67a","scripts":{"build":"tsc","start":"node dist/index.js"},"_npmUser":{"name":"dongsik","email":"ehdtlr9376@gmail.com"},"_npmVersion":"11.12.1","description":"Google Analytics 4 MCP Server","directories":{},"_nodeVersion":"25.9.0","dependencies":{"open":"^10.0.0","googleapis":"^144.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ga4-mcp_0.1.0_1775833209976_0.42330313418491206","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@dongsik/ga4-mcp","version":"0.1.1","_id":"@dongsik/ga4-mcp@0.1.1","maintainers":[{"name":"dongsik","email":"ehdtlr9376@gmail.com"}],"bin":{"ga4-mcp":"dist/index.js"},"dist":{"shasum":"1bd0d6f03eda2a693c9a6517f0ff6845b404c96d","tarball":"https://registry.npmjs.org/@dongsik/ga4-mcp/-/ga4-mcp-0.1.1.tgz","fileCount":9,"integrity":"sha512-T8Eb1ly4dxLRSousGEfxnDSwBobjsE5Lo5q+18KoImHgAVH5HwungxzdvwgJyAjk1OUdZNpGc6ldwAAw4qROzg==","signatures":[{"sig":"MEYCIQDp7IrBhZ+f9BrvrybVXhlL+NtePSqHuXrrUzdVsi2qIAIhAIy6xoMS/X51n2jHBAjncyAkHIlLrUGutKrBaIWYbTO1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39805},"type":"module","gitHead":"1696711ff0aec7ba3c43e3c5ed57adc1f17d54be","scripts":{"build":"tsc","start":"node dist/index.js"},"_npmUser":{"name":"dongsik","email":"ehdtlr9376@gmail.com"},"_npmVersion":"11.12.1","description":"Google Analytics 4 MCP Server","directories":{},"_nodeVersion":"25.9.0","dependencies":{"open":"^10.0.0","googleapis":"^144.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ga4-mcp_0.1.1_1775874315975_0.8666446556618979","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@dongsik/ga4-mcp","version":"0.1.2","_id":"@dongsik/ga4-mcp@0.1.2","maintainers":[{"name":"dongsik","email":"ehdtlr9376@gmail.com"}],"bin":{"ga4-mcp":"dist/index.js"},"dist":{"shasum":"807267c12ed9acee08f32db223fcca13cab657a4","tarball":"https://registry.npmjs.org/@dongsik/ga4-mcp/-/ga4-mcp-0.1.2.tgz","fileCount":9,"integrity":"sha512-LE3TdE9ToyU9DJrbM+67094HWS5HyiXfuulFGQku0YTYw/qfKHCnI6TYKgr/Vu2U4EGSiWvsqBYBqEIEI7i+RQ==","signatures":[{"sig":"MEUCIQCHfkAzok0L3o4fJVJjBLKP02k+cSvZbXJOJAqJy12PLAIgU3GCv6ORUtfLMVrqMFFtpEapIXjl9i4hpiNGUCXG6HI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39921},"type":"module","gitHead":"1696711ff0aec7ba3c43e3c5ed57adc1f17d54be","scripts":{"build":"tsc && chmod +x dist/index.js","start":"node dist/index.js"},"_npmUser":{"name":"dongsik","email":"ehdtlr9376@gmail.com"},"_npmVersion":"11.12.1","description":"Google Analytics 4 MCP Server","directories":{},"_nodeVersion":"25.9.0","dependencies":{"open":"^10.0.0","googleapis":"^144.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ga4-mcp_0.1.2_1775874452721_0.7666359972842849","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@dongsik/ga4-mcp","version":"0.1.3","description":"Google Analytics 4 MCP Server","license":"MIT","type":"module","bin":{"ga4-mcp":"dist/index.js"},"scripts":{"build":"tsc && chmod +x dist/index.js","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"},"gitHead":"26cbc2a793cefb88c4aa61e34150254522c03a54","_id":"@dongsik/ga4-mcp@0.1.3","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-3iQYf4dNuautFQweS7j12779hNNb0tI5AhAcGVeRt6PYjQociHDrje1qlGuwT95saGD3jdL1EquFKbJdOkinWg==","shasum":"2180c8506759048c6597fb27084eba73f64c8263","tarball":"https://registry.npmjs.org/@dongsik/ga4-mcp/-/ga4-mcp-0.1.3.tgz","fileCount":9,"unpackedSize":40654,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDwA0Hvt3xue16YrWNSS3UxHMPTWBPIm9xTfOrbzYysowIgAgEXRZtibmiH0/AmVnoZxMN0xOuH+kaAdiUFkLtDins="}]},"_npmUser":{"name":"dongsik","email":"ehdtlr9376@gmail.com"},"directories":{},"maintainers":[{"name":"dongsik","email":"ehdtlr9376@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ga4-mcp_0.1.3_1775885969059_0.6225768801357467"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-10T15:00:09.885Z","modified":"2026-04-11T05:39:29.345Z","0.1.0":"2026-04-10T15:00:10.121Z","0.1.1":"2026-04-11T02:25:16.158Z","0.1.2":"2026-04-11T02:27:32.852Z","0.1.3":"2026-04-11T05:39:29.253Z"},"description":"Google Analytics 4 MCP Server","maintainers":[{"name":"dongsik","email":"ehdtlr9376@gmail.com"}],"readme":"# ga4-mcp\n\n[![npm](https://img.shields.io/npm/v/@dongsik/ga4-mcp)](https://www.npmjs.com/package/@dongsik/ga4-mcp)\n\n[한국어](docs/README.ko.md)\n\nAn MCP server for querying and analyzing Google Analytics 4 data directly from Claude Desktop.\n\n```bash\nnpx -y @dongsik/ga4-mcp\n```\n\n## Features\n\n### Basic Queries\n| Tool | Description |\n|---|---|\n| `list_accounts` | List GA4 accounts |\n| `list_properties` | List properties within an account |\n| `run_report` | Run custom reports with flexible metric/dimension combinations and dimension filters |\n\n### Page & Traffic Analysis\n| Tool | Description |\n|---|---|\n| `get_top_pages` | Top pages by pageviews, sessions, avg. duration, bounce rate |\n| `get_traffic_sources` | Traffic source breakdown by source/medium |\n\n### User Analysis\n| Tool | Description |\n|---|---|\n| `get_user_overview` | User overview (total users, new users, sessions, pageviews, etc.) |\n| `get_users_by_country` | Users by country |\n| `get_users_by_device` | Users by device category (desktop, mobile, tablet) |\n\n### Trends & Realtime\n| Tool | Description |\n|---|---|\n| `get_trend_by_date` | Daily trends (pageviews, sessions, users over time) |\n| `get_realtime` | Realtime active users and pageviews |\n\n### Campaign Analysis\n| Tool | Description |\n|---|---|\n| `get_campaign_performance` | Campaign performance (sessions, users, conversions, bounce rate). Filter by campaign name |\n| `get_utm_breakdown` | Full UTM parameter analysis (campaign, source, medium, content, keyword) |\n| `compare_campaigns` | Compare performance across multiple campaigns |\n\n### Metadata\n| Tool | Description |\n|---|---|\n| `get_metadata` | List all available metrics and dimensions |\n| `search_metadata` | Search metrics/dimensions by keyword |\n| `list_categories` | List metric/dimension categories |\n\n## Prerequisites\n\n### Google Cloud Console Setup\n\n1. Create or select a project in [Google Cloud Console](https://console.cloud.google.com/)\n2. **APIs & Services → Library** → Enable \"Google Analytics Data API\"\n3. **APIs & Services → Library** → Enable \"Google Analytics Admin API\"\n4. **APIs & Services → OAuth consent screen** → Set User Type to **External**, add your Google account as a test user\n5. **APIs & Services → Credentials** → Create **OAuth 2.0 Client ID** (type: Desktop app)\n6. Download the JSON file → this is your `client_secret.json`\n\n### Find your GA4 Property ID\n\n1. Go to [Google Analytics](https://analytics.google.com)\n2. Bottom left **Admin (gear icon)** → **Property Settings**\n3. Your **Property ID** is the numeric ID shown at the top (e.g. `417304962`)\n\n## Installation\n\n### Claude Desktop Configuration\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ga\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=@dongsik/ga4-mcp\", \"ga4-mcp\"],\n      \"env\": {\n        \"GA_CLIENT_SECRET_PATH\": \"/path/to/client_secret.json\",\n        \"GA4_PROPERTY_ID\": \"123456789\"\n      }\n    }\n  }\n}\n```\n\n> Windows path example: `\"C:\\\\Users\\\\username\\\\client_secret.json\"`\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add ga4 -- npx --package=@dongsik/ga4-mcp ga4-mcp\n```\n\nSet environment variables:\n\n```bash\nclaude mcp add ga4 -e GA_CLIENT_SECRET_PATH=/path/to/client_secret.json -e GA4_PROPERTY_ID=123456789 -- npx --package=@dongsik/ga4-mcp ga4-mcp\n```\n\n### Environment Variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `GA_CLIENT_SECRET_PATH` | Yes | Path to OAuth client_secret.json file |\n| `GA4_PROPERTY_ID` | No | Default GA4 property ID. When set, you don't need to specify propertyId for each request |\n\n### First Run\n\nOn first launch, a browser window will open for Google OAuth login. After authentication, the token is saved locally and subsequent requests will authenticate automatically.\n\n## Usage Examples\n\nAsk questions in natural language through Claude Desktop:\n\n- \"Show me the top pages for the last 30 days\"\n- \"Analyze traffic sources for this month\"\n- \"Compare users this week vs last week\"\n- \"Show user distribution by country\"\n- \"How many users are online right now?\"\n- \"Show performance for the spring_sale campaign\"\n- \"Break down traffic by UTM parameters\"\n- \"Compare campaign A vs campaign B\"\n- \"What campaign-related dimensions are available in GA4?\"\n\n## Dimension Filters\n\nUse dimension filters in `run_report` to narrow down results:\n\n```\n\"Show only pages starting with /blog for the last 30 days\"\n→ dimensionFilter: { fieldName: \"pagePath\", matchType: \"BEGINS_WITH\", value: \"/blog\" }\n\n\"Analyze only traffic from google\"\n→ dimensionFilter: { fieldName: \"sessionSource\", matchType: \"EXACT\", value: \"google\" }\n```\n\nSupported match types: `EXACT`, `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, `REGEXP`\n\n## License\n\nMIT\n","readmeFilename":"README.md","license":"MIT"}