内容
# 营销MCP
MCP服务器，暴露Google Ads，Google Analytics 4和Meta Ads作为LLM的工具。 使用PHP构建。 支持两种传输模式： **stdio** （本地，单用户）和 **HTTP** （Docker，多用户）。
## 目录
- [服务器设置（Docker + HTTP）](#服务器设置docker--http)
- [本地设置（stdio）](#本地设置stdio)
- [从Claude授权平台](#从claude授权平台)
- [用户管理CLI](#用户管理cli)
- [工具参考](#工具参考)
## 服务器设置（Docker + HTTP）
HTTP模式允许多个用户使用自己的API凭证从任何设备连接。 SSL由Nginx Proxy Manager或任何其他反向代理处理。
### 1 — 启动容器
```bash
git clone https://github.com/and-ri/marketing-mcp.git
cd marketing-mcp
docker compose up -d
```
服务器监听 **8080** 端口。 在Nginx Proxy Manager中：添加一个代理主机→转发到 `localhost:8080` →启用SSL。
### 2 — 创建用户
```bash
docker compose exec mcp php users.php add alice
```
打印一个Bearer令牌。 保存它 — 这是Claude的凭证。
### 3 — 连接Claude
添加到 `~/.claude.json` （全局）或 `.mcp.json` （项目级）：
```json
{
"mcpServers": {
"marketing": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer <token from step 2>"
}
}
}
}
```
### 4 — 授权平台
连接后，告诉Claude调用 `auth_status` — 它将报告缺少的内容并指导您完成设置。 或者只需询问： *"为我设置Google Ads"* ，Claude将引导您完成每个步骤。
参见 [从Claude授权平台](#从claude授权平台) 获取详细信息。
### 5 — 维护
```bash
docker compose logs -f mcp # live logs
docker compose up -d --build mcp # rebuild after code changes
docker compose exec mcp php users.php list # list all users
```
## 本地设置（stdio）
适用于单用户本地使用，无Docker。
```bash
composer install
php auth.php # interactive OAuth2 flow — opens browser, writes .env
```
MCP客户端配置：
```json
{
"mcpServers": {
"marketing": {
"command": "php",
"args": ["/path/to/marketing-mcp/app.php"]
}
}
}
```
## 从Claude授权平台
在HTTP模式下，凭证按用户存储在SQLite中。 通过MCP工具授权 - 不需要终端访问。
### 工作原理
1. 调用 **`auth_start_google`** 或 **`auth_start_meta`** — 返回OAuth网址
2. 在浏览器中打开网址并授权访问
3. 浏览器显示“授权！您可以关闭此标签页。”
4. 调用 **`auth_finish_google`** 或 **`auth_finish_meta`** — 保存凭证
服务器的OAuth回调端点是 `https://yourdomain.com/oauth/callback` 。 此网址必须在Google和Meta开发者控制台中注册（工具描述中包含确切的添加位置说明）。
### 授权工具
| 工具 | 功能 |
|---|---|
| `auth_status` | 显示已配置的平台和缺少的内容 |
| `auth_start_google` | 启动Google OAuth2。 工具描述包含Google Cloud Console的完整设置指南 |
| `auth_finish_google` | 完成Google身份验证，保存刷新令牌 |
| `auth_start_meta` | 启动Meta OAuth2。 工具描述包含Meta开发者门户的完整设置指南 |
| `auth_finish_meta` | 完成Meta身份验证，保存长期令牌（〜60天） |
| `auth_start_tiktok` / `auth_finish_tiktok` | TikTok Ads OAuth2流程 |
| `auth_set_clarity` | 保存Microsoft Clarity API令牌（单步 - Clarity没有OAuth） |
| `auth_set_rybbit` | 保存自托管Rybbit `base_url` + `api_key`（单步 - Rybbit没有OAuth） |
> **基于令牌的集成** （Microsoft Clarity，Rybbit）不使用OAuth - 没有浏览器步骤。 只需调用 `auth_set_clarity` / `auth_set_rybbit` 并输入令牌即可。
### Google — 您需要
在调用 `auth_start_google` 之前：
1. **Google Cloud项目** — [console.cloud.google.com](https://console.cloud.google.com)
2. **启用API** — Google Ads API + Google Analytics Data API
3. **OAuth客户端** — 类型： *Web应用程序* ，重定向URI： `https://yourdomain.com/oauth/callback`
4. **开发者令牌** — [ads.google.com/aw/apicenter](https://ads.google.com/aw/apicenter)
`auth_start_google` 工具描述包括上述所有步骤的逐步说明。Claude可以读取它们并交互式地指导您。
### Meta — 您需要
在调用 `auth_start_meta` 之前：
1. **Meta开发者应用程序** — [developers.facebook.com](https://developers.facebook.com)，类型：Business
2. **Marketing API产品** 添加到应用程序
3. **Facebook Login产品** 添加，重定向URI `https://yourdomain.com/oauth/callback` 注册
4. **应用程序ID和应用程序密钥** — 设置 → 基本
`auth_start_meta` 工具描述包括逐步说明。 Meta令牌在〜60天后过期 - 需要时使用 `auth_start_meta` + `auth_finish_meta` 重新授权。
## 用户管理CLI
在Docker容器内运行：
```bash
# 创建用户 - 打印Bearer令牌
docker compose exec mcp php users.php add <name>
# 列出所有用户和令牌
docker compose exec mcp php users.php list
# 显示用户的环境变量（值被遮蔽）
docker compose exec mcp php users.php env:show <name>
# 手动设置单个环境变量
docker compose exec mcp php users.php env:set <name> META_ACCESS_TOKEN EAAxxxxx
# 从.env文件导入所有变量
docker compose exec -T mcp php users.php env:import <name> < credentials.env
# 重置受损的令牌
docker compose exec mcp php users.php token:reset <name>
# 删除用户和所有凭证
docker compose exec mcp php users.php remove <name>
```
按用户存储的凭证（与 `.env.example` 中的键名相同）：
| 平台 | 键 |
|---|---|
| Google Ads | `GOOGLE_ADS_DEVELOPER_TOKEN` ， `GOOGLE_ADS_CLIENT_ID` ， `GOOGLE_ADS_CLIENT_SECRET` ， `GOOGLE_ADS_REFRESH_TOKEN` ， `GOOGLE_ADS_LOGIN_CUSTOMER_ID` *(MCC only)* |
| Google Analytics 4 | `GOOGLE_CLIENT_ID` ， `GOOGLE_CLIENT_SECRET` ， `GOOGLE_REFRESH_TOKEN` |
| Meta Ads | `META_APP_ID` ， `META_APP_SECRET` ， `META_ACCESS_TOKEN` |
## 工具参考
### 查找账户ID
| 平台 | 如何查找ID |
|---|---|
| Google Ads `customer_id` | 10位数字，无破折号。 首先调用 `google_ads_list_customers` 。 |
| GA4 `property_id` | 数值ID - Analytics → 管理 → 属性设置。 例如 `123456789` 。 |
| Meta `account_id` | 数值ID，带有或不带有 `act_` 前缀。 首先调用 `meta_get_ad_accounts` 。 |
## Google Ads工具
`date_range` 值： `TODAY` `YESTERDAY` `LAST_7_DAYS` `LAST_14_DAYS` `LAST_30_DAYS` `THIS_MONTH` `LAST_MONTH` `THIS_QUARTER` `LAST_QUARTER` `THIS_YEAR` `LAST_YEAR`
货币价值以 **微** 表示 - 除以1,000,000即可获得实际金额。
### `google_ads_list_customers`
列出所有可访问的Google Ads账户。 首先调用此命令以获取 `customer_id` 值。
**参数：** 无
**返回：** `{ customers: [{ customer_id, resource_name }], total }`
### `google_ads_get_campaigns`
具有花费、点击量、展示次数、点击率、每次点击成本、每次展示成本、转化次数和转化价值的活动。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
| `status` | 字符串 | 否 | `ALL` - `ENABLED` \| `PAUSED` \| `REMOVED` \| `ALL` |
### `google_ads_get_ad_groups`
具有出价和指标的广告组。 可选地限定在一个活动中。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
### `google_ads_get_keywords`
具有质量评分（1-10）、匹配类型、有效每次点击出价、展示份额的关键词。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `ad_group_id` | 字符串 | 否 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
| `limit` | 整数 | 否 | `200` |
### `google_ads_get_search_terms`
用户实际搜索触发广告的关键词。 用于发现否定关键词。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
| `limit` | 整数 | 否 | `200` |
### `google_ads_get_ads`
具有创意文本（RSA标题/描述，ETA字段）和审批状态的单个广告。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `ad_group_id` | 字符串 | 否 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
| `limit` | 整数 | 否 | `100` |
### `google_ads_get_geo_performance`
按地理位置（`country_criterion_id`）显示性能。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
| `limit` | 整数 | 否 | `100` |
### `google_ads_get_account_metrics`
顶级账户摘要：总花费、点击量、展示次数、转化次数、展示份额、失去IS（预算和排名）。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
### `google_ads_query`
执行任何 [GAQL](https://developers.google.com/google-ads/api/docs/query/overview) 查询。 当其他工具无法满足您的报告需求时使用（购物、视频、更改历史、受众等）。
| 参数 | 类型 | 必需 |
|---|---|---|
| `customer_id` | 字符串 | 是 |
| `query` | 字符串 | 是 |
```sql
-- 更改历史记录
SELECT change_event.change_date_time, change_event.change_resource_type, change_event.user_email
FROM change_event WHERE change_event.change_date_time DURING LAST_14_DAYS
ORDER BY change_event.change_date_time DESC LIMIT 50
-- 购物性能
SELECT shopping_performance_view.resource_name, metrics.clicks, metrics.cost_micros
FROM shopping_performance_view WHERE segments.date DURING LAST_30_DAYS
```
### `google_ads_get_change_history`
账户更改历史记录 - 谁更改了什么以及何时（活动、广告组、出价、预算、广告、标准）。 Google仅保留 **最近30天** 的记录。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `days` | 整数 | 否 | `14` （最大30） |
| `resource_type` | 字符串 | 否 | - 例如 `CAMPAIGN` ， `AD_GROUP` ， `AD_GROUP_AD` ， `CAMPAIGN_BUDGET` |
| `limit` | 整数 | 否 | `500` （最大10000） |
**返回：** `{ changes: [...], total, days }`
### `google_ads_get_negative_keyword_lists`
共享的否定关键词列表（共享集类型 `NEGATIVE_KEYWORDS` ）：列表、关键词成员以及每个列表附加的活动。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
**返回：** `{ lists: [...], members: [...], attachments: [...], total_lists }`
### `google_ads_get_negative_keywords`
直接在活动和广告组级别应用的否定关键词（不包括共享列表）。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `limit` | 整数 | 否 | `500` |
**返回：** `{ campaign_level: [...], ad_group_level: [...], total }`
### `google_ads_get_audiences`
受众段/用户列表，包括自定义上传的Customer Match列表（`user_list.type = CRM_BASED`）与匹配率，以及remarketing、类似、基于规则的列表和组合受众。 显示大小、成员资格和资格。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `list_type` | 字符串 | 否 | - 例如 `CRM_BASED` ， `REMARKETING` ， `SIMILAR` ， `RULE_BASED` , `LOGICAL` |
**返回：** `{ user_lists: [...], audiences: [...], total_user_lists }`
### `google_ads_get_audience_performance`
受众段附加到活动和广告组（`campaign_audience_view` ， `ad_group_audience_view`）的性能展示次数、点击次数、成本和转化次数，每个受众。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `customer_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `date_range` | 字符串 | 否 | `LAST_30_DAYS` |
| `limit` | 整数 | 否 | `200` |
**返回：** `{ ad_group_level: [...], campaign_level: [...], total, date_range }`
### `google_ads_get_creatives`
创意参考和见解。 使用结果中的 `creative.id`）来获取图像/复制。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `account_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `adset_id` | 字符串 | 否 | - |
| `date_preset` | 字符串 | 否 | `LAST_30D` |
| `limit` | 整数 | 否 | `50` |
---
## Google Analytics 4 工具
`start_date` / `end_date`：相对（`today`，`yesterday`，`7daysAgo`，`30daysAgo`）或绝对`YYYY-MM-DD`。
### `ga4_run_report`
自定义报告，包含GA4浏览器中的任意维度、指标。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `dimensions` | 字符串[] | 是 | - |
| `metrics` | 字符串[] | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
| `limit` | 整数 | 否 | `100` |
---
### `ga4_run_realtime_report`
当前活跃用户，可选按维度细分。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `dimensions` | 字符串[] | 否 | `["country"]` |
| `metrics` | 字符串[] | 否 | `["activeUsers"]` |
---
### `ga4_get_audience_overview`
每日细目：`totalUsers`，`newUsers`，`sessions`，`bounceRate`，`averageSessionDuration`，`engagedSessions`，`engagementRate` 按 `newVsReturning` 分割。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
---
### `ga4_get_traffic_sources`
按渠道组、来源和媒介显示会话数。包含 `sessions`、`totalUsers`、`bounceRate`、`conversions`、`totalRevenue`。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
| `limit` | 整数 | 否 | `50` |
---
### `ga4_get_top_pages`
按浏览量显示的热门页面。返回 `pagePath`、`pageTitle`、`totalUsers`、`bounceRate`、`engagementRate`、`conversions`。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
| `limit` | 整数 | 否 | `50` |
---
### `ga4_get_conversions`
按 `eventName` 和渠道组显示转化事件。返回 `conversions`、`totalRevenue`、`sessions`。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
---
### `ga4_get_ecommerce`
收入、交易、销售商品、平均订单价值。如果属性没有电子商务事件，则返回空值。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
| `limit` | 整数 | 否 | `50` |
---
### `ga4_get_geo_breakdown`
按国家和城市显示流量。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
| `limit` | 整数 | 否 | `50` |
---
### `ga4_get_device_breakdown`
按设备类别、操作系统和浏览器显示流量。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `property_id` | 字符串 | 是 | - |
| `start_date` | 字符串 | 否 | `30daysAgo` |
| `end_date` | 字符串 | 否 | `today` |
---
## Meta Ads 工具
`account_id` 接受数值ID（带有或不带有 `act_` 前缀）。
`date_preset`： `today` `yesterday` `last_3d` `last_7d` `last_14d` `last_28d` `last_30d` `last_90d` `this_month` `last_month` `this_quarter` `last_year` `lifetime`
货币价值以账户货币表示（不是微妙）。
### `meta_get_ad_accounts`
列出所有可访问的广告账户。 首先调用此命令以获取 `account_id` 值。
**参数：** 无
`account_status` 代码： `1`= 活跃， `2`= 禁用， `3`= 未结算， `7`= 待审核， `101`= 已关闭。
---
### `meta_get_campaigns`
具有预算、目标和见解的活动（花费、覆盖范围、展示次数、点击次数、点击率、每次点击成本、每次展示成本、ROAS、`actions`）。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `account_id` | 字符串 | 是 | - |
| `date_preset` | 字符串 | 否 | `last_30d` |
| `status` | 字符串[] | 否 | `["ACTIVE","PAUSED"]` |
| `limit` | 整数 | 否 | `50` |
`actions` 在见解中为 `[{ action_type, value }]`. 常见类型： `link_click` ， `lead` ， `purchase` ， `add_to_cart` ， `initiate_checkout` ， `complete_registration`.
---
### `meta_get_adsets`
具有定位（`age_min/max`，`genders`，`geo_locations`，`interests`，`custom_audiences`，`publisher_platforms`）和见解的广告组。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `account_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `date_preset` | 字符串 | 否 | `last_30d` |
| `limit` | 整数 | 否 | `50` |
---
### `meta_get_ads`
具有创意参考和见解的单个广告。 使用 `creative.id` 从结果中获取图像/复制。
| 参数 | 类型 | 必需 | 默认 |
|---|---|---|---|
| `account_id` | 字符串 | 是 | - |
| `campaign_id` | 字符串 | 否 | - |
| `adset_id` | 字符串 | 否 | - |
| `date_preset` | 字符串 | 否 | `last_30d` |
| `limit` | 整数 | 否 | `50` |
---
### `meta_get_insights`
聚合洞察数据，可选细分。比针对广告活动/广告组/广告的单独洞察更灵活。
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
| `account_id` | 字符串 | 是 | — |
| `object_id` | 字符串 | 否 | — |
| `object_type` | 字符串 | 否 | `account` — `account` \| `campaign` \| `adset` \| `ad` |
| `date_preset` | 字符串 | 否 | `last_30d` |
| `breakdowns` | 字符串数组 | 否 | 无 |
| `limit` | 整数 | 否 | `100` |
`breakdowns`: `age` `gender` `country` `region` `impression_device` `placement` `platform_position` `publisher_platform`
注意：某些细分组合不兼容。 unsure 时每次只使用一种。
---
### `meta_get_custom_audiences`
自定义和相似受众，包含规模估计和数据来源。
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
| `account_id` | 字符串 | 是 | — |
| `limit` | 整数 | 否 | `50` |
`subtype` 值： `CUSTOM` `WEBSITE` `APP` `LOOKALIKE` `ENGAGEMENT` `VIDEO` `OFFLINE_CONVERSION`
---
### `meta_get_pixels`
Meta Pixel 及最后触发时间。
| 参数 | 类型 | 必填 |
|---|---|---|
| `account_id` | 字符串 | 是 |
---
### `meta_get_creatives`
广告创意资产：标题、正文、图片网址、CTA 类型、目标网址。
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
| `account_id` | 字符串 | 是 | — |
| `limit` | 整数 | 否 | `50` |
---
## Microsoft Clarity 工具
行为分析，补充 GA4 — Clarity 揭示用户体验摩擦（愤怒点击、无效点击、快速返回、滚动深度、JS 错误），而 GA4 未涵盖。认证方式为静态项目令牌（`CLARITY_API_TOKEN`），在 Clarity → **设置 → 数据导出 → 生成新 API 令牌** 中生成。无 OAuth 流程。
> **限制（Clarity API）：** 数据仅涵盖 **最近 1-3 天**，每天最多 **10 次请求**，响应限制为 **1000 行**（无分页），结果以 UTC 时区显示。
### `clarity_get_insights`
实时洞察项目数据：流量、滚动深度、参与时间、无效/愤怒/快速返回点击、过度滚动和脚本错误。可按最多三个维度细分。
| 参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
| `num_of_days` | 整数 | 否 | `1` — `1` \| `2` \| `3` |
| `dimension1` | 字符串 | 否 | — `Browser` \| `Device` \| `Country/Region` \| `OS` \| `Source` \| `Medium` \| `Campaign` \| `Channel` \| `URL` |
| `dimension2` | 字符串 | 否 | — 第二个细分维度 |
| `dimension3` | 字符串 | 否 | — 第三个细分维度 |
**返回：** `{ num_of_days, metrics: [{ metricName, information: [...] }] }`
---
## Rybbit 工具
来自 **自托管** [Rybbit](https://rybbit.com) 实例的只读分析。设置 `RYBBIT_BASE_URL`（您的实例，无尾斜杠）和 `RYBBIT_API_KEY`（设置 → 账户 → API 密钥）。所有工具都需要 `site_id`，可选时间范围（`start_date`、`end_date`、`time_zone`）和 `filters`（JSON 编码数组）。
### `rybbit_get_overview`
概览指标：会话数、页面浏览量、用户数、每次会话页面数、跳出率、会话时长。
### `rybbit_get_overview_timeseries`
时间序列概览指标。添加 `bucket`（`minute` \| `five_minutes` \| `hour` \| `day` \| `week` \| `month`，默认为 `day`）。
### `rybbit_get_sessions`
分页会话列表，包含地理位置、设备、浏览器、来源、页面、时长。添加 `page`、`limit`，可选 `user_id`。
### `rybbit_get_event_names`
自定义事件名称及其发生次数 — 跟踪转化和关键操作。
### `rybbit_get_performance`
核心网页生命指标（LCP、CLS、INP、FCP、TTFB）在 p50/p75/p90/p99 的表现。有助于评估着陆页质量。
### `rybbit_get_errors`
按名称分组的 JavaScript 错误，包含次数、会话次数和百分比。添加 `page`、`limit`。
### `rybbit_get_goals`
转化目标，包含总转化次数、会话次数和转化率。添加 `page`、`page_size`。
| 通用参数 | 类型 | 必填 | 默认值 |
|---|---|---|---|
| `site_id` | 字符串 | 是 | — |
| `start_date` | 字符串 | 否 | — ISO 日期 |
| `end_date` | 字符串 | 否 | — ISO 日期 |
| `time_zone` | 字符串 | 否 | UTC |
| `filters` | 字符串 | 否 | — JSON 数组 |
---
## 常见工作流
**"这个月的 Google Ads 表现如何？"**
1. `google_ads_list_customers` → 获取 `customer_id`
2. `google_ads_get_account_metrics`，设置 `date_range: THIS_MONTH`
3. `google_ads_get_campaigns`，用于按广告活动细分
**"哪些 Meta 广告活动的 ROAS 最佳？"**
1. `meta_get_ad_accounts` → 获取 `account_id`
2. `meta_get_campaigns` → 查看 `insights.action_values[purchase] / insights.spend`
**"我的网站流量来自哪里？"**
1. `ga4_get_traffic_sources`，使用您的 `property_id`
**"哪些搜索词浪费了预算？"**
1. `google_ads_get_search_terms` → 查找高支出且无转化的词
**"全面的跨平台审计"**
1. `google_ads_get_account_metrics` — 顶级支出/转化
2. `google_ads_get_campaigns` + `google_ads_get_keywords` — 质量评分、展示份额
3. `google_ads_get_search_terms` — 无关查询
4. `meta_get_campaigns` + `meta_get_insights`，设置 `breakdowns: ["age"]` 和 `["placement"]`
5. `ga4_get_traffic_sources` — 付费与自然流量的划分
6. `ga4_get_conversions` — 哪些事件实际转化
---
## 错误参考
所有工具返回的错误均在 MCP `content` 数组中（带有 `isError: true`）。常见原因：
| 错误 | 原因 | 解决方法 |
|---|---|---|
| `PERMISSION_DENIED` | OAuth 令牌无法访问该账户 | 在 Google Ads 中检查账户访问权限，或使用 `google_ads_list_customers` 查看可访问的账户 |
| `INVALID_CUSTOMER_ID` | 格式错误或账户不存在 | 使用 10 位数字格式，无需破折线 |
| `quota exceeded` | Google Ads API 每日配额已达上限 | 等待 24 小时或申请更高配额 |
| `(#100)` | Meta：无效参数或缺少权限 | 检查范围 — 确保已授予 `ads_read`、`ads_management`、`business_management` |
| `OAuth2 token expired` | Google 刷新令牌被撤销或过期 | 调用 `auth_start_google` + `auth_finish_google` |
| `Error validating access token` | Meta 令牌过期（约 60 天） | 调用 `auth_start_meta` + `auth_finish_meta` |
| `Developer token is not approved` | Google Ads 开发令牌仅具有基本访问权限 | 在 ads.google.com/aw/apicenter 申请标准访问权限 |
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器