mcp-dv360

marekzabrodsky/mcp-dv360

3.2

If you are the rightful owner of mcp-dv360 and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The DV360 MCP Server is a comprehensive Model Context Protocol server that enables AI assistants to manage Google Display & Video 360 advertising campaigns through natural language.

Tools
17
Resources
0
Prompts
0

DV360 MCP Server

Python 3.10+ License: MIT MCP

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with full programmatic access to Google Display & Video 360 (DV360) advertising platform. Built with Claude Code for the community.

🤖 Enable your AI assistant to manage DV360 campaigns through natural language!

🆕 Latest Update - REAL Performance Metrics!

🎯 BREAKTHROUGH: Real Performance Data Access!

  • ⚡ Bid Manager API v2 integration - Access to REAL performance data
  • 📊 Actual impressions, clicks, CTR - No more placeholder data
  • 💰 Real spend and revenue metrics
  • 🎯 Custom performance reports with any metrics
  • 📈 8 new performance tools - Now 25 total tools!

Previous enhancements also included:

  • ✨ 12 additional tools for detailed DV360 management
  • 📋 Detailed insertion order info with budget & settings
  • 💰 Line item details including bidding strategies
  • 🎯 Targeting configuration access
  • 🎨 Creative management and assignments

🔥 What you can now do with REAL data:

"Get REAL impressions and clicks for campaign 52866149"
"Show me actual CTR for line item 11111 in last 30 days"
"What are the real conversion numbers for advertiser 1076318578?"
"Create custom performance report with actual spend data"
"Get real revenue metrics for my campaigns"

🚀 Features

📊 Comprehensive Data Access

  • 80+ Real Advertisers - Access your complete DV360 account structure
  • Campaigns & Insertion Orders - Full campaign hierarchy navigation
  • Line Items & Creatives - Detailed creative and line item management
  • Audiences & Targeting - Complete audience and targeting insights
  • Performance Analytics - Real-time reporting and metrics

🛠️ 25 Powerful Tools (with REAL Performance Metrics!)

Basic Account Management
  • list_advertisers - Show all advertisers in your account
  • get_advertiser_summary - Comprehensive advertiser overview with counts
Campaign Management
  • list_campaigns - List campaigns for an advertiser
  • list_active_campaigns - Show only active campaigns
  • search_campaigns - Search campaigns by name
  • get_campaign_details - Detailed campaign information
Structural Navigation 🔍
  • list_insertion_orders - Browse insertion orders for campaigns
  • get_insertion_order_details - NEW! Detailed IO info with budget & settings
  • list_line_items_for_io - ENHANCED! List line items with IO filtering
  • get_line_item_details - NEW! Complete line item data with bidding strategy
  • get_targeting_options - NEW! View detailed targeting configurations
Creative & Audience Management 🎨
  • list_creatives - NEW! Browse all creatives for advertiser
  • get_creative_details - NEW! Detailed creative info & assignments
  • list_audiences_for_advertiser - ENHANCED! View audience segments
  • get_audience_details - NEW! Complete audience data & targeting
Performance & Reporting 📈
  • get_campaign_performance_summary - NEW! Get impressions, clicks, CTR & conversions
  • list_saved_reports - NEW! Browse existing reports & queries
🎯 REAL Performance Metrics (Bid Manager API v2) ⚡
  • get_real_campaign_performance - REAL DATA! Actual impressions, clicks, CTR
  • get_real_advertiser_performance - REAL DATA! Complete advertiser metrics
  • get_real_line_item_performance - REAL DATA! Line item performance stats
  • create_custom_performance_report - NEW! Custom reports with real metrics
  • get_performance_report_data - NEW! Download report data
  • list_performance_queries - NEW! Browse existing performance reports
  • get_available_performance_metrics - NEW! List all available metrics
  • get_available_date_ranges - NEW! List all date range options

🚀 Quick Start

# Clone the repository
git clone https://github.com/marekzabrodsky/mcp-dv360.git
cd mcp-dv360

# Install dependencies
pip install -r requirements.txt

# Set up credentials (see INSTALL.md for details)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"

# Test the installation
python3 final_verification.py

|

Installation

Prerequisites

  • Python 3.10 or higher
  • Google Cloud Platform account with DV360 API access
  • Either Service Account credentials or OAuth 2.0 credentials
  • Claude Desktop application

Setup

  1. Clone the repository:
git clone <repository-url>
cd dv360-mcp-server-claude
  1. Install dependencies:
pip install -r requirements.txt
  1. Configure authentication:

Choose one of the following authentication methods:

Option A: Service Account (Recommended for production)
  1. Create a service account in Google Cloud Console
  2. Download the JSON key file
  3. Set environment variable:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
Option B: OAuth 2.0 (For development/testing)
  1. Create OAuth 2.0 credentials in Google Cloud Console
  2. Set environment variables:
export OAUTH_CLIENT_ID="your-client-id"
export OAUTH_CLIENT_SECRET="your-client-secret"
export OAUTH_REFRESH_TOKEN="your-refresh-token"
  1. Optional configuration: Create a .env file in the project root:
# Authentication (choose one method)
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
# OR
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_REFRESH_TOKEN=your-refresh-token

# Optional settings
LOG_LEVEL=INFO
MAX_RETRIES=3
TIMEOUT_SECONDS=30

Usage

Running the Server

Run the MCP server using stdio transport:

python -m src.dv360_mcp_server.server

Integration with Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dv360": {
      "command": "python",
      "args": ["-m", "src.dv360_mcp_server.server"],
      "cwd": "/path/to/dv360-mcp-server-claude",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/credentials.json"
      }
    }
  }
}

Example Usage with Claude

Once connected, you can interact with DV360 through natural language:

💬 Usage Examples

Account Overview

"Show me all my advertisers"
"Get a summary for advertiser 1076318578"  
"How many campaigns do I have active?"

Campaign Analysis

"List campaigns for advertiser 1076318578"
"Search for campaigns containing 'Bourdon' in advertiser 1076318578"
"Show me details for campaign 52866149"
"Get performance summary for campaign 52866149 in last 30 days"

Deep Dive Analysis 🔍

"List insertion orders for advertiser 1076318578"
"Show me detailed info for insertion order 67890 including budget"
"List line items for insertion order 67890"
"Get complete line item details with bidding strategy for 11111"
"Show me targeting options for line item 11111"

Creative & Audience Management 🎨

"List all creatives for advertiser 1076318578"
"Get details for creative 99999"
"Show me audience segments for advertiser 1076318578"
"Get details for audience 55555"
"What saved reports are available?"

🎯 REAL Performance Analysis ⚡

"Get REAL impressions and clicks for campaign 52866149"
"Show me actual CTR for line item 11111 in last 30 days"
"What are real conversion numbers for advertiser 1076318578?"
"Get actual spend and revenue for my campaigns"
"Create custom performance report with specific metrics"
"What performance metrics are available?"
"Download report data for query 987654321"

Performance Reporting

"Get campaign performance for advertiser 1076318578 and campaign 52866149"
"Show me saved reports"
"Generate a performance summary for the last 30 days"

Advanced Queries

"Find all active campaigns with 'holiday' in the name"
"Show me a complete overview of my top advertiser"
"List all line items that are currently paused"

API Coverage

This MCP server covers the following DV360 API endpoints:

  • advertisers.list() - List advertisers
  • advertisers.campaigns.list() - List campaigns
  • advertisers.lineItems.list() - List line items
  • firstAndThirdPartyAudiences.list() - List audiences
  • queries.list() - List reports
  • advertisers.campaigns.create() - Create campaigns
  • advertisers.lineItems.patch() - Update line items
  • queries.create() - Generate reports
  • firstAndThirdPartyAudiences.create() - Create audiences

Development

Project Structure

dv360-mcp-server-claude/
├── src/
│   └── dv360_mcp_server/
│       ├── __init__.py
│       ├── server.py          # Main MCP server implementation
│       ├── dv360_client.py    # DV360 API client wrapper
│       └── config.py          # Configuration management
├── requirements.txt           # Python dependencies
└── README.md                 # This file

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Security Considerations

  • Always use service account credentials in production
  • Never commit credentials to version control
  • Implement proper access controls in your Google Cloud project
  • Monitor API usage and implement rate limiting as needed
  • Review the MCP security documentation

Troubleshooting

Authentication Issues

  • Verify your credentials file path
  • Check that the service account has proper DV360 API permissions
  • Ensure the DV360 API is enabled in your Google Cloud project

API Errors

  • Check your DV360 account permissions
  • Verify advertiser IDs and other resource IDs
  • Monitor API quotas and limits

Connection Issues

  • Verify the MCP server is running
  • Check Claude Desktop configuration
  • Review server logs for error messages

License

This project is licensed under the MIT License. See LICENSE file for details.

Resources

📈 Real Performance Data

This MCP server has been tested with real DV360 data:

  • ✅ 80+ Advertisers including Nakladatelství Bourdon, Dr. Theiss, Moravian Silesian Tourism
  • ✅ 22+ Campaigns per advertiser with real performance data
  • ✅ 25+ Insertion Orders and 100+ Creatives per advertiser
  • ✅ Full API Coverage - All major DV360 endpoints implemented
  • ✅ Production Ready - Tested with actual Google credentials

🏗️ Built With

  • Python 3.10+ - Modern async/await patterns
  • MCP SDK 1.2.0+ - Latest Model Context Protocol
  • Google API Client - Official Google API libraries
  • Claude Code - Built collaboratively with Claude

🤝 Contributing

This project was created collaboratively with Claude Code and is open for community contributions:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Submit a pull request

⭐ Show Your Support

If this MCP server helps you manage your DV360 campaigns, please give it a star! It helps others discover this tool.

Built with ❤️ by the Claude Code community

Note: This is an unofficial integration. Google Display & Video 360 is a trademark of Google LLC.