MCP谷歌分析服务器
用于Google Analytics 4的模型上下文协议（MCP）服务器，提供与 谷歌分析数据API （用于阅读报告）以及 测量协议v2 （用于发送事件）。
](https://www.npmjs.com/package/mcp-google-analytics) 
⚡ 令牌优化-请先阅读此内容！
重要：谷歌分析报告可以返回消耗大量代币的大型数据集。此服务器的设计考虑了令牌优化：
- 所有读取工具默认为10个结果 -调整
limit根据需要设置参数 - 使用特定日期范围 -避免一次查询多年的数据
- 仅选择所需的维度/指标 -不要要求一切
- 检查 代币激活.md 了解详细的最佳实践
查看专用 代币优化指南 用于最小化令牌使用的策略。
🚀 快速开始
看 QUICKSTART.md 获取5分钟的安装指南，或按照以下安装步骤进行操作。
📦 安装
选项1：通过npm全局安装
npm install -g mcp-google-analytics选项2：与npx一起使用（无需安装）
npx mcp-google-analytics🔧 配置
此服务器需要不同的凭据来读取数据和发送事件：
用于读取数据（Google Analytics Data API）
你需要一个 服务帐户 访问您的GA4房产：
- 首选 谷歌云控制台
- 创建或选择项目
- 启用 谷歌分析数据API
- 创建服务帐户：
- 转到“IAM和管理”>“服务帐户” - 点击“创建服务帐户” - 为其命名（例如，“GA4 MCP阅读器”） - 授予“查看器”角色 - 创建JSON密钥并下载
- 将服务帐户电子邮件添加到您的GA4物业：
- 转到GA4管理>物业访问管理 - 添加具有“查看器”角色的服务帐户电子邮件
- 获取您的房产ID：
- 转到GA4管理>属性设置 - 复制属性ID（数字，例如“123456789”）
用于发送事件（测量协议）
你需要一个 测量ID 和 API秘密:
- 转到GA4管理>数据流
- 选择您的数据流（网络、iOS或Android）
- 复制 测量ID （格式：
G-XXXXXXXXXX) - 点击“测量协议API机密”
- 单击“创建”生成新的API机密
- 复制机密值
环境变量
设置这些环境变量：
# For Data API (reading)
export GA_SERVICE_ACCOUNT_JSON=/path/to/service-account.json
# Or provide JSON directly:
# export GA_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"..."}'
export GA_PROPERTY_ID=123456789
# For Measurement Protocol (writing)
export GA_MEASUREMENT_ID=G-XXXXXXXXXX
export GA_API_SECRET=your-api-secret-here🔌 与Claude Desktop集成
添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"google-analytics": {
"command": "npx",
"args": ["-y", "mcp-google-analytics"],
"env": {
"GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
"GA_PROPERTY_ID": "123456789",
"GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
"GA_API_SECRET": "your-api-secret"
}
}
}
}或者，如果全局安装：
{
"mcpServers": {
"google-analytics": {
"command": "mcp-google-analytics",
"env": {
"GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
"GA_PROPERTY_ID": "123456789",
"GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
"GA_API_SECRET": "your-api-secret"
}
}
}
}更新配置后重新启动Claude Desktop。
🎯 与Cursor集成
添加到光标MCP设置文件中：
macOS/Linux: ~/.cursor/mcp.json 视窗: %USERPROFILE%\.cursor\mcp.json
{
"mcpServers": {
"google-analytics": {
"command": "npx",
"args": ["-y", "mcp-google-analytics"],
"env": {
"GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
"GA_PROPERTY_ID": "123456789",
"GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
"GA_API_SECRET": "your-api-secret"
}
}
}
}更新配置后重新启动Cursor。
🛠️ 可用工具
谷歌分析数据API（阅读数据）
ga_run_report
运行具有维度和指标的自定义报告。
常见尺寸: date, city, country, deviceCategory, browser, pagePath, eventName, sessionSource, sessionMedium, sessionCampaignName
通用指标: activeUsers, sessions, screenPageViews, conversions, totalRevenue, engagementRate, averageSessionDuration
示例:
{
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"dimensions": [{"name": "city"}],
"metrics": [{"name": "activeUsers"}],
"limit": 10
}ga_run_realtime_report
获取实时数据（过去30分钟）。
示例:
{
"metrics": [{"name": "activeUsers"}],
"dimensions": [{"name": "country"}],
"limit": 10
}ga_get_metadata
获取您物业的所有可用维度和指标。
警告：返回500多个项目。谨慎使用。
ga_list_accounts
列出服务帐户可访问的所有GA帐户。
ga_list_properties
列出GA4属性，可选择按帐户ID筛选。
ga_get_property
获取配置属性的详细信息。
ga_list_data_streams
列出已配置属性的数据流。
ga_run_pivot_report
运行具有行/列维度的透视表报告。
示例:
{
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"dimensions": [{"name": "country"}, {"name": "deviceCategory"}],
"metrics": [{"name": "activeUsers"}],
"pivots": [{"fieldNames": ["deviceCategory"], "limit": 5}]
}ga_run_funnel_report
运行漏斗分析以跟踪用户进度。
示例:
{
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"funnelSteps": [
{"name": "page_view"},
{"name": "add_to_cart"},
{"name": "begin_checkout"},
{"name": "purchase"}
]
}ga_batch_run_reports
在单个请求中运行多个报告。
警告：可以返回大型数据集。每批限制为2-5份报告。
测量协议（发送事件）
ga_send_event
将自定义事件发送到GA4。
示例:
{
"events": [{
"name": "button_click",
"params": {
"button_id": "cta_signup",
"page": "/landing"
}
}],
"user_id": "user123"
}ga_validate_event
发送前验证事件（使用调试端点）。
ga_send_pageview
发送页面浏览事件。
示例:
{
"page_location": "https://example.com/products",
"page_title": "Products",
"user_id": "user123"
}ga_send_purchase
发送电子商务购买事件。
示例:
{
"transaction_id": "T12345",
"value": 99.99,
"currency": "USD",
"items": [{
"item_id": "SKU123",
"item_name": "Product Name",
"price": 99.99,
"quantity": 1
}]
}ga_send_login
发送登录事件。
ga_send_signup
发送用户注册事件。
ga_send_add_to_cart
发送添加到购物车事件。
ga_send_begin_checkout
发送结账启动事件。
📖 使用示例
看 示例.md 以获取西班牙语的实际使用示例。
示例：按国家/地区获取用户（过去7天）
Show me active users by country for the last 7 days克劳德将使用 ga_run_report:
{
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"dimensions": [{"name": "country"}],
"metrics": [{"name": "activeUsers"}],
"limit": 10,
"orderBys": [{"metric": {"metricName": "activeUsers"}, "desc": true}]
}示例：跟踪购买
Send a purchase event for order #12345, $99.99 USD克劳德将使用 ga_send_purchase:
{
"transaction_id": "12345",
"value": 99.99,
"currency": "USD",
"items": [{
"item_id": "product_1",
"item_name": "Example Product",
"price": 99.99,
"quantity": 1
}]
}🔍 调试
通过设置启用调试日志记录：
export DEBUG=mcp-google-analytics:*对于测量协议，使用 ga_validate_event 在实时发送之前检查事件。
🤝 贡献
欢迎投稿！请随时提交拉取请求。
📄 许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
🔗 链接
🆘 支持
对于问题和疑问：
📝 更新日志
看 更改日志.md 版本历史。
______________________________________________________________________