dv360-ads-mcp-server by caspercrause - MCP Server

DV360 MCP Server

A Model Context Protocol (MCP) server for Display & Video 360 (DV360) that provides entity management and performance reporting capabilities.

Sample Report Demo

View Sample Performance Report - See what's possible with this MCP server.

The sample report demonstrates:

Campaign and Insertion Order performance analysis
Age group segmentation from Line Item targeting
Floodlight conversion funnel (Find Branch → Product View → Add to Cart → Purchase)
Creative banner size performance comparison

Architecture

This server integrates with two Google APIs to provide comprehensive DV360 access:

Display & Video 360 API (v4): Entity management (campaigns, insertion orders, creatives)
Bid Manager API (v2): Performance reporting (impressions, clicks, conversions, costs)

Features

Floodlight Conversion Tracking: Segment conversions by specific floodlight activities (product views, add-to-cart, purchases, etc.)
Entity Management: List and retrieve campaigns, insertion orders, and creatives with filtering and ordering
Performance Reporting: Run synchronous reports with comprehensive metrics
Advanced Filtering: Filter entities by status, dates, and other properties
Custom Ordering: Sort results by any field in ascending or descending order
Flexible Input Types: Accepts dimensions/metrics as lists or comma-separated strings
Comprehensive Metrics: Access all DV360 metrics and dimensions

Prerequisites

1. Google Cloud Project Setup

Create or select a project in Google Cloud Console
Enable the required APIs:
- Display & Video 360 API (for entity management)
- DoubleClick Bid Manager API (for reporting)
Create a service account:
- Go to IAM & Admin > Service Accounts
- Create a new service account
- Download the JSON key file

2. DV360 Platform Setup

Your service account needs to be granted access in the DV360 platform:

Log into Display & Video 360
Navigate to Settings > Access Management
Click Add User
Enter the service account email (found in your JSON key file: client_email)
Assign appropriate permissions:
- Read & Write access for entity management tools
- Read access is sufficient if you only need reporting
Select the partner(s) and advertiser(s) the service account should access

DV360 Partner ID Location

Note: The service account email looks like: your-service-account@your-project.iam.gserviceaccount.com

3. Find Your Partner ID (Optional)

If you want to use list_advertisers without specifying a partner ID each time:

Method 1: From any DV360 URL

Log into DV360
Look at the URL: https://displayvideo.google.com/ng_nav/p/[PARTNER_ID]/...
The number after /p/ is your Partner ID

Method 2: From Partner Settings

Log into DV360
Navigate to Partner Settings > Basic Details
The URL will be: https://displayvideo.google.com/ng_nav/p/{partner-id}/details
Your Partner ID is visible in the URL
Or Locate using the below image as reference

DV360 Partner ID Location

Once you have your Partner ID, add it to your .env file:

DV360_PARTNER_ID=your_partner_id

Installation

Step 1: Create a Virtual Environment

Create a dedicated virtual environment for the DV360 MCP server:

# 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

Important: Keep the virtual environment activated for all subsequent commands.

Step 2: Clone and Install

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

# Install dependencies
pip install -r requirements.txt

Step 3: Configure Environment Variables

Create the environment configuration file:

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

Edit the .env file with your credentials:

# 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

REMEMBER: The DV360_SERVICE_ACCOUNT value MUST be the entire JSON content on a single line. Do NOT format it with line breaks.

How to get the service account JSON:

Go to Google Cloud Console → IAM & Admin → Service Accounts
Select your DV360 service account
Go to "Keys" tab → "Add Key" → "Create new key" → JSON
Open the downloaded JSON file
Copy the entire content and paste it as one line in the .env file

Step 4: Configure MCP in Your AI Client

For Claude Desktop:

Open your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the DV360 MCP server configuration:

Important: Replace /full/path/to/ with the actual paths on your system.

For Cursor:

Open Cursor settings or the Command Palette ⌘ + ⇧ + P
Go to "MCP Servers" section
Add a new server with:
- Name: dv360
- Command: /full/path/to/dv360-ads-mcp-server/dv360_venv/bin/python
- Arguments: /full/path/to/dv360-ads-mcp-server/server.py
Optional: add Current Working Directory (cwd):
- Current Working Directory: /full/path/to/dv360-ads-mcp-server

Example file:

{
  "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"
    }
  }
}

Step 5: Restart and Test

Restart your AI client (Claude Desktop or Cursor) completely
Test the connection by asking about DV360 in a new chat

Expected behavior: You should see DV360 tools available when you mention DV360-related topics.

Troubleshooting Setup Issues

Virtual Environment Issues:

# 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)

Service Account JSON Issues:

Verify the JSON is exactly one line in your .env file
Check that there are no extra quotes around the JSON
Ensure the service account has DV360 API access

MCP Configuration Issues:

Double-check file paths in the MCP config
Ensure the virtual environment Python path is correct
Try restarting your AI client after configuration changes

Testing the Setup:

Once configured, try asking: "List my DV360 advertisers" in a new chat. If you get a response with advertiser data, the setup is working.

Available Tools

Entity Management Tools

Campaigns

list_campaigns - List all campaigns for an advertiser

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

get_campaign - Get detailed information about a specific campaign

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

Insertion Orders

list_insertion_orders - List all insertion orders for an advertiser

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

get_insertion_order - Get detailed information about a specific insertion order

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

Creatives

list_creatives - List all creatives for an advertiser

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

get_creative - Get detailed information about a specific creative

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

Advertisers

list_advertisers - List all advertisers under a partner

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

Filtering Examples

All list tools support filtering by various criteria:

Entity Status:

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

Date Ranges:

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

Ordering:

displayName (ascending)
displayName desc (descending)
updateTime desc

Reporting Tools

Usage

Running a Report

The main tool is run_report, which creates a query, runs it synchronously, downloads the CSV, and returns JSON data:

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"
)

Available Parameters

start_date (required): Start date in YYYY-MM-DD format
end_date (required): End date in YYYY-MM-DD format
dimensions (required): Dimensions to group by (list or comma-separated string)
metrics (required): Metrics to retrieve (list or comma-separated string)
advertiser_ids (optional): Filter by advertiser ID(s)
campaign_ids (optional): Filter by campaign ID(s)
insertion_order_ids (optional): Filter by insertion order ID(s)
line_item_ids (optional): Filter by line item ID(s)
report_name (optional): Name for the report (default: "MCP Report")

Flexible Input Types

You can provide dimensions and metrics in multiple ways:

# 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"

Available Dimensions

Floodlight Conversion Dimensions

Segment conversions by specific floodlight activities:

FILTER_FLOODLIGHT_ACTIVITY_ID: Floodlight Activity ID (unique identifier)
FILTER_FLOODLIGHT_ACTIVITY: Floodlight Activity Name (human-readable name)
FILTER_ADVERTISER_CURRENCY: Required when tracking revenue/conversion value

⚠️ IMPORTANT LIMITATION: Floodlight dimensions can ONLY be used with conversion metrics. You CANNOT query impressions, clicks, or costs by floodlight activity.

Compatible metrics with Floodlight dimensions:

✅ METRIC_TOTAL_CONVERSIONS - Total conversions (all attribution)
✅ METRIC_LAST_CLICKS - Post-click conversions
✅ METRIC_LAST_IMPRESSIONS - Post-view conversions
✅ METRIC_REVENUE_ADVERTISER - Conversion value (requires FILTER_ADVERTISER_CURRENCY)
❌ Impressions, Clicks, Costs - NOT compatible

Example conversion actions you can track:

product_view - Product page views
add_to_cart - Items added to cart
purchase - Purchase completions
sign_up - Sign up for a service

Entity Dimensions

FILTER_ADVERTISER: Advertiser ID
FILTER_ADVERTISER_NAME: Advertiser name
FILTER_MEDIA_PLAN: Campaign ID
FILTER_MEDIA_PLAN_NAME: Campaign name
FILTER_INSERTION_ORDER: Insertion Order ID
FILTER_INSERTION_ORDER_NAME: Insertion Order name
FILTER_LINE_ITEM: Line Item ID
FILTER_LINE_ITEM_NAME: Line Item name
FILTER_CREATIVE: Creative ID
FILTER_CREATIVE_TYPE: Creative type

Time Dimensions

FILTER_DATE: Date
FILTER_WEEK: Week
FILTER_MONTH: Month
FILTER_YEAR: Year

Geographic Dimensions

FILTER_COUNTRY: Country
FILTER_REGION: Region/State
FILTER_CITY: City
FILTER_DMA: Designated Market Area

Device Dimensions

FILTER_DEVICE_TYPE: Device type
FILTER_BROWSER: Browser
FILTER_OS: Operating system
FILTER_ENVIRONMENT: Environment (App/Web)

Available Metrics

Impression Metrics

METRIC_IMPRESSIONS: Total impressions
METRIC_VIEWABLE_IMPRESSIONS: Viewable impressions
METRIC_MEASURABLE_IMPRESSIONS: Measurable impressions

Click Metrics

METRIC_CLICKS: Total clicks
METRIC_CTR: Click-through rate

Conversion Metrics (ONLY these work with Floodlight Dimensions)

METRIC_TOTAL_CONVERSIONS: Total conversions (all types)
METRIC_LAST_CLICKS: Post-click conversions
METRIC_LAST_IMPRESSIONS: Post-view conversions
METRIC_REVENUE_ADVERTISER: Revenue/conversion value (requires FILTER_ADVERTISER_CURRENCY dimension)

Important: These are the ONLY metrics that can be combined with FILTER_FLOODLIGHT_ACTIVITY dimensions!

Note: The API uses METRIC_LAST_CLICKS and METRIC_LAST_IMPRESSIONS (not METRIC_POST_CLICK_CONVERSIONS or METRIC_POST_VIEW_CONVERSIONS).

Cost Metrics

METRIC_MEDIA_COST_ADVERTISER: Media cost
METRIC_BILLABLE_COST_ADVERTISER: Billable cost
METRIC_TOTAL_MEDIA_COST_ADVERTISER: Total media cost

Revenue Metrics

METRIC_REVENUE_ADVERTISER: Revenue
METRIC_PROFIT_ADVERTISER: Profit
METRIC_ROI_RATIO: ROI ratio

Video Metrics

METRIC_VIDEO_COMPLETION_RATE: Video completion rate
METRIC_TRUEVIEW_VIEWS: TrueView views
METRIC_VIDEO_QUARTILE_25_RATE: 25% completion
METRIC_VIDEO_QUARTILE_50_RATE: 50% completion
METRIC_VIDEO_QUARTILE_75_RATE: 75% completion
METRIC_VIDEO_QUARTILE_100_RATE: 100% completion

For the complete list, see: https://developers.google.com/bid-manager/reference/rest/v2/filters-metrics

Using Tools Together for Performance Analysis

How it comes together (no code needed):

Discover entities: campaigns, insertion orders, line items, creatives.
Pull performance: impressions, clicks, conversions, cost, and revenue-ready metrics with currency included.
Break down results: by funnel step (Floodlight), age (from line items), creative size, geography, or device.
Ship it: generate the HTML report and host it (e.g., GitHub Pages) to share with stakeholders.

What you can explore

Campaign/IO performance with view vs click conversions.
Funnel health: Find Branch → Product View → Add to Cart → Purchase.
Which creatives and sizes are most efficient.
Which age groups (from line items) respond best.
Geographic or device splits to refine targeting.

Want hands-on examples?

Run the sample report locally: python3 -m http.server 8000 and open http://localhost:8000/dv360_performance_report.html.
Or view the live sample: https://caspercrause.github.io/dv360-ads-mcp-server/templates/dv360_performance_report.html

Response Format

The server returns a JSON response with the following structure:

{
  "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
  }
}

Troubleshooting

Service Account Errors

Ensure your service account has access to your DV360 account
Verify the service account JSON is correctly formatted in the DV360_SERVICE_ACCOUNT environment variable
Check that the service account has the Display & Video 360 API enabled
Make sure the JSON string is properly escaped and quoted in your .env file