DV360 MCP服务器

用于显示和视频360（DV360）的模型上下文协议（MCP）服务器，提供实体管理和性能报告功能。

示例报告演示

查看示例性能报告 -看看这个MCP服务器有什么可能。

示例报告显示：

活动和插入订单绩效分析
根据行项目定位进行年龄组细分
泛光灯转换漏斗（查找分支→ 产品视图→ 加入购物车→ 购买）
创意横幅尺寸性能比较

建筑

此服务器与两个Google API集成，提供全面的DV360访问：

显示和视频360 API（v4）：实体管理（活动、插入订单、创意）
投标经理API（v2）：绩效报告（印象、点击、转化、成本）

特性

泛光灯转换跟踪：按特定泛光灯活动（产品查看、添加到购物车、购买等）进行细分转换
实体管理：通过过滤和排序列出和检索活动、插入顺序和创意
绩效报告：运行具有全面指标的同步报告
高级过滤：按状态、日期和其他属性筛选实体
定制订购：按升序或降序按任何字段对结果进行排序
灵活的输入类型：接受以列表或逗号分隔的字符串形式的维度/指标
综合指标：访问所有DV360指标和维度

先决条件

1.谷歌云项目设置

在中创建或选择项目谷歌云控制台
启用所需的API：

- 显示和视频360 API （用于实体管理） - 双击投标经理API （用于报告）

创建服务帐户：

- 转到IAM和管理>服务帐户 - 创建新的服务帐户 - 下载JSON密钥文件

2.DV360平台设置

您的服务帐户需要被授予DV360平台的访问权限：

登录到显示和视频360
导航至设置 > 访问管理
点击 添加用户
输入服务帐户电子邮件（在JSON密钥文件中找到： client_email)
分配适当的权限：

- 读写实体管理工具的访问权限 - 阅读如果您只需要报告，则访问权限就足够了

选择服务帐户应访问的合作伙伴和广告商

DV360 Partner ID Location

备注：服务帐户电子邮件看起来像： your-service-account@your-project.iam.gserviceaccount.com

3.查找您的合作伙伴ID（可选）

如果你想使用 list_advertisers 无需每次指定合作伙伴ID：

方法1：从任何DV360 URL

登录DV360
请查看URL： https://displayvideo.google.com/ng_nav/p/[PARTNER_ID]/...
后面的数字 /p/ 是您的合作伙伴ID

方法2：从合作伙伴设置

登录DV360
导航至 合作伙伴设置 > 基本细节
URL将是： https://displayvideo.google.com/ng_nav/p/{partner-id}/details
您的合作伙伴ID在URL中可见
或使用下图作为参考进行定位

DV360 Partner ID Location

获得合作伙伴ID后，将其添加到您的 .env 文件：

DV360_PARTNER_ID=your_partner_id

安装

步骤1：创建虚拟环境

为DV360 MCP服务器创建专用虚拟环境：

# Create virtual environment
python3 -m venv dv360_venv

# Activate the virtual environment
source dv360_venv/bin/activate  # On macOS/Linux
# OR
dv360_venv\Scripts\activate     # On Windows

重要：为所有后续命令保持虚拟环境处于激活状态。

步骤2：克隆并安装

# Clone the repository
git clone 
cd dv360-ads-mcp-server

# Install dependencies
pip install -r requirements.txt

步骤3：配置环境变量

创建环境配置文件：

# Copy the example file
cp .env.example .env

编辑 .env 使用您的凭据文件：

# REQUIRED: Your service account JSON (MUST be a single line)
DV360_SERVICE_ACCOUNT={"type":"service_account","project_id":"your-project","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","client_email":"your-service-account@your-project.iam.gserviceaccount.com","client_id":"...","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/your-service-account%40your-project.iam.gserviceaccount.com"}

# OPTIONAL: Your DV360 Partner ID (speeds up advertiser listing)
DV360_PARTNER_ID=your_partner_id

记住：The DV360_SERVICE_ACCOUNT value必须是单行中的整个JSON内容。不要用换行符格式化。

如何获取服务帐户JSON：

转到谷歌云控制台→ IAM和管理员→ 服务帐户
选择您的DV360服务帐户
转到“密钥”选项卡→ “添加密钥”→ “创建新密钥”→ JSON
打开下载的JSON文件
复制整个内容并将其作为一行粘贴到.env文件中

步骤4：在AI客户端中配置MCP

对于Claude Desktop：

打开您的Claude Desktop配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

添加DV360 MCP服务器配置：

重要：替换 /full/path/to/ 使用系统上的实际路径。

对于光标：

打开光标设置或命令选项板 ⌘ + ⇧ + P

转到“MCP服务器”部分

使用以下命令添加新服务器：

- 名字: dv360 - 命令: /full/path/to/dv360-ads-mcp-server/dv360_venv/bin/python - 参数: /full/path/to/dv360-ads-mcp-server/server.py

_可选的_: 添加当前工作目录（cwd）：

- 当前工作目录: /full/path/to/dv360-ads-mcp-server

示例文件：

{
  "mcpServers": {
    "dv360": {
      "command": "/full/path/to/dv360-ads-mcp-server/dv360_venv/bin/python/python",
      "args": ["/full/path/to/dv360-ads-mcp-server/server.py"],
      "cwd": "/full/path/to/dv360-ads-mcp-server"
    }
  }
}

步骤5：重新启动并测试

重新启动AI客户端 （克劳德桌面或光标）完全
测试连接 在新聊天中询问DV360

预期行为：当您提到DV360相关主题时，您应该看到可用的DV360工具。

解决安装问题

虚拟环境问题：

# Make sure you're in the right directory and venv is activated
pwd  # Should show dv360-ads-mcp-server
which python  # Should show path to dv360_venv/bin/python (/full/path/to/dv360-ads-mcp-server)

服务帐户JSON问题：

验证JSON是否正好是您的 .env 文件
检查JSON周围是否没有额外的引号
确保服务帐户具有DV360 API访问权限

MCP配置问题：

仔细检查MCP配置中的文件路径
确保虚拟环境Python路径正确
在配置更改后尝试重新启动AI客户端

测试设置：

配置后，尝试询问： *“列出我的DV360广告商”* 在一次新的聊天中。如果您收到广告商数据的回复，则设置正常。

可用工具

实体管理工具

活动

list_campaigns -列出广告商的所有活动

list_campaigns(
    advertiser_id="123456",
    filter='entityStatus="ENTITY_STATUS_ACTIVE"',
    order_by="displayName",
    page_size=100
)

get_campaign -获取特定活动的详细信息

get_campaign(
    advertiser_id="123456",
    campaign_id="789012"
)

插入订单

list_insert_orders -列出广告商的所有插入订单

list_insertion_orders(
    advertiser_id="123456",
    filter='entityStatus="ENTITY_STATUS_ACTIVE"',
    order_by="displayName",
    page_size=100
)

get_insert_order -获取特定插入顺序的详细信息

get_insertion_order(
    advertiser_id="123456",
    insertion_order_id="789012"
)

创意作品

list_创意 -列出广告商的所有创意

list_creatives(
    advertiser_id="123456",
    filter='entityStatus="ENTITY_STATUS_ACTIVE"',
    order_by="displayName",
    page_size=100
)

get_creative -获取特定创意的详细信息

get_creative(
    advertiser_id="123456",
    creative_id="789012"
)

广告商

list_广告主 -列出合作伙伴下的所有广告商

list_advertisers(
    partner_id="123456",  # Optional if DV360_PARTNER_ID is set
    order_by="displayName",
    page_size=100
)

过滤示例

所有列表工具都支持按各种条件进行筛选：

实体状态：

entityStatus="ENTITY_STATUS_ACTIVE"
entityStatus="ENTITY_STATUS_PAUSED"
entityStatus="ENTITY_STATUS_ARCHIVED"

日期范围：

updateTime>"2025-01-01T00:00:00Z"
updateTime<"2025-12-31T23:59:59Z"

订购：

displayName （升序）
displayName desc （下降）
updateTime desc

报告工具

用法

运行报告

主要工具是 run_report，它创建查询，同步运行查询，下载CSV，并返回JSON数据：

run_report(
    start_date="2025-01-01",
    end_date="2025-01-31",
    dimensions=["FILTER_DATE", "FILTER_ADVERTISER_NAME", "FILTER_MEDIA_PLAN_NAME"],
    metrics=["METRIC_IMPRESSIONS", "METRIC_CLICKS", "METRIC_CTR", "METRIC_TOTAL_CONVERSIONS"],
    advertiser_ids="123456789"
)

可用参数

开始日期 （必填）：开始日期，格式为YYYY-MM-DD
结束日期 （必填）：YYYY-MM-DD格式的结束日期
尺寸（必填）：分组依据的维度（列表或逗号分隔字符串）
指标（必填）：要检索的指标（列表或逗号分隔的字符串）
广告商ID （可选）：按广告商ID筛选
campaign_ids （可选）：按活动ID筛选
insertion_order_ids （可选）：按插入顺序ID筛选
line_item_ids （可选）：按行项目ID筛选
报告名称 （可选）：报告名称（默认：“MCP报告”）

灵活的输入类型

您可以通过多种方式提供维度和指标：

# As a list
dimensions=["FILTER_DATE", "FILTER_ADVERTISER_NAME"]

# As a comma-separated string
dimensions="FILTER_DATE, FILTER_ADVERTISER_NAME"

# Same for IDs
advertiser_ids=["123", "456"]  # or
advertiser_ids="123, 456"

可用尺寸

泛光灯转换尺寸

按特定泛光灯活动划分的细分转换：

FILTER_FLOODLIGHT_ACTIVITY_ID：泛光灯活动ID（唯一标识符）
FILTER_FLOODLIGHT_ACTIVITY：泛光灯活动名称（人类可读名称）
FILTER_ADVERTISER_CURRENCY：跟踪收入/转换值时需要

⚠️ 重要限制：泛光灯尺寸可以仅与转换指标一起使用。你不能按泛光灯活动查询展示次数、点击次数或成本。

与泛光灯尺寸兼容的指标：

✅ METRIC_TOTAL_CONVERSIONS -总转化率（所有归因）
✅ METRIC_LAST_CLICKS -点击后转化
✅ METRIC_LAST_IMPRESSIONS -后视图转换
✅ METRIC_REVENUE_ADVERTISER -转换值（必填 FILTER_ADVERTISER_CURRENCY)
❌ 印象、点击、成本-不兼容

您可以跟踪的转换操作示例：

product_view -产品页面浏览量
add_to_cart -已添加到购物车的商品
purchase -购买完成情况
sign_up -注册服务

实体尺寸

FILTER_ADVERTISER：广告商ID
FILTER_ADVERTISER_NAME：广告商名称
FILTER_MEDIA_PLAN：活动ID
FILTER_MEDIA_PLAN_NAME：活动名称
FILTER_INSERTION_ORDER：插入订单ID
FILTER_INSERTION_ORDER_NAME：插入订单名称
FILTER_LINE_ITEM：行项目ID
FILTER_LINE_ITEM_NAME：行项目名称
FILTER_CREATIVE：创意ID
FILTER_CREATIVE_TYPE：创意型

时间维度

FILTER_DATE：日期
FILTER_WEEK：周
FILTER_MONTH：月份
FILTER_YEAR：年份

地理维度

FILTER_COUNTRY：国家
FILTER_REGION：地区/州
FILTER_CITY城市
FILTER_DMA：指定市场区域

设备尺寸

FILTER_DEVICE_TYPE：设备类型
FILTER_BROWSER：浏览器
FILTER_OS：操作系统
FILTER_ENVIRONMENT：环境（应用程序/网络）

可用指标

印象指标

METRIC_IMPRESSIONS：总印象
METRIC_VIEWABLE_IMPRESSIONS：可查看的印象
METRIC_MEASURABLE_IMPRESSIONS：可测量的印象

点击指标

METRIC_CLICKS：总点击次数
METRIC_CTR：点击率

转换指标（仅适用于泛光灯尺寸）

METRIC_TOTAL_CONVERSIONS：总转化率（所有类型）
METRIC_LAST_CLICKS：点击后转换
METRIC_LAST_IMPRESSIONS：后视图转换
METRIC_REVENUE_ADVERTISER：收入/转换价值（需要 FILTER_ADVERTISER_CURRENCY 尺寸）

重要：这些是唯一可以与以下指标相结合的指标 FILTER_FLOODLIGHT_ACTIVITY 尺寸！

备注：API使用 METRIC_LAST_CLICKS 和 METRIC_LAST_IMPRESSIONS （不是 METRIC_POST_CLICK_CONVERSIONS 或 METRIC_POST_VIEW_CONVERSIONS).

成本指标

METRIC_MEDIA_COST_ADVERTISER：媒体成本
METRIC_BILLABLE_COST_ADVERTISER：可计费成本
METRIC_TOTAL_MEDIA_COST_ADVERTISER：媒体总成本

收入指标

METRIC_REVENUE_ADVERTISER：收入
METRIC_PROFIT_ADVERTISER：利润
METRIC_ROI_RATIO：投资回报率

视频指标

METRIC_VIDEO_COMPLETION_RATE：视频完成率
METRIC_TRUEVIEW_VIEWS：TrueView视图
METRIC_VIDEO_QUARTILE_25_RATE：完成25%
METRIC_VIDEO_QUARTILE_50_RATE：完成50%
METRIC_VIDEO_QUARTILE_75_RATE：完成75%
METRIC_VIDEO_QUARTILE_100_RATE：100%完成

有关完整列表，请参阅：https://developers.google.com/bid-manager/reference/rest/v2/filters-metrics

一起使用工具进行性能分析

它是如何组合在一起的（不需要代码）：

发现实体：活动、插入订单、行项目、创意。
拉动绩效：展示、点击、转化、成本和收入就绪指标，包括货币。
分解结果：按漏斗步（泛光灯）、年龄（从行项目）、创意大小、地理位置或设备。
发布：生成HTML报告并将其托管（例如GitHub Pages）以与利益相关者共享。

你可以探索什么

查看与点击转换的活动/IO性能。
漏斗健康：查找分支→ 产品视图→ 加入购物车→ 购买。
哪些创意和尺寸最有效。
哪些年龄组（从行项目中）反应最好。
地理或设备分割以优化定位。

想要动手的例子吗？

在本地运行示例报告： python3 -m http.server 8000 并开放 http://localhost:8000/dv360_performance_report.html.
或查看实时样本：https://caspercrause.github.io/dv360-ads-mcp-server/templates/dv360_performance_report.html

响应格式

服务器返回具有以下结构的JSON响应：

{
  "success": true,
  "data": [
    {
      "Date": "2025-01-01",
      "Advertiser": "My Advertiser",
      "Campaign": "My Campaign",
      "Impressions": 10000,
      "Clicks": 150,
      "CTR": 1.5,
      "Total Conversions": 10
    }
  ],
  "metadata": {
    "query_id": "12345",
    "report_id": "67890",
    "date_range": {
      "start_date": "2025-01-01",
      "end_date": "2025-01-31"
    },
    "dimensions": ["FILTER_DATE", "FILTER_ADVERTISER_NAME", "FILTER_MEDIA_PLAN_NAME"],
    "metrics": ["METRIC_IMPRESSIONS", "METRIC_CLICKS", "METRIC_CTR", "METRIC_TOTAL_CONVERSIONS"],
    "row_count": 31
  }
}

故障排除

服务帐户错误

确保您的服务帐户可以访问您的DV360帐户
验证DV360_service_account环境变量中的服务帐户JSON格式是否正确
检查服务帐户是否已启用Display&Video 360 API
确保JSON字符串在.env文件中正确转义和引用

查询错误

某些维度/度量组合不兼容
首先在DV360 UI中测试您的查询，以确保其正常工作
检查官方文档对于有效组合

速率限制

谷歌对投标经理API实施费率限制
如果您达到了速率限制，请降低查询频率或批量处理您的请求

Dv360 Ads MCP Server

快速接入

详细介绍