@cesteral/dv360-mcp

@cesteral/dv360-mcp

DV360 MCP Server - Campaign entity management and configuration for Google Display & Video 360.

Purpose

Management server for DV360 campaign entities. Provides CRUD operations for campaigns, insertion orders, line items, creatives, and other DV360 entities via the Display & Video 360 API v4.

Choose Your Path

• Self-host this connector when you want direct control of credentials, infrastructure, and DV360 API access.
• Use Cesteral Intelligence when the workflow needs approvals before spend commits, credential brokering, auditability, and cross-platform execution.

Self-host quickstart | Compare OSS vs Cesteral Intelligence | Book a workflow demo

Features

• Schema-Driven Architecture: Auto-generated TypeScript types and Zod schemas from DV360 OpenAPI specification
• Dynamic Entity System: Supports 11 DV360 entity types with minimal configuration
• Production-Grade: OpenTelemetry instrumentation, structured logging, rate limiting, JWT authentication
• MCP Protocol: Full Model Context Protocol implementation with Streamable HTTP and stdio transports
• Claude Desktop Integration: Seamless integration with Claude Desktop for AI-powered DV360 management

Context Efficiency Notes

• Tool schemas are intentionally simplified for MCP registration; use resources for full schema details.
• Keep tool descriptions concise and fetch workflow guidance from prompts/resources.
• For tools with outputSchema, prioritize structuredContent as the canonical full payload.

Quick Start with Claude Desktop

The fastest way to get started is using Claude Desktop:

• Get service account credentials - See SERVICE_ACCOUNT_SETUP.md
• Build the server:

  cd packages/dv360-mcp && pnpm run build
  

• Configure Claude Desktop with your service account file path
• Start using DV360 tools directly in Claude Desktop

See CLAUDE_DESKTOP_SETUP.md for detailed setup instructions.

Current Implementation Status

✅ Production-Ready (all tools fully functional)

The server is built with production-grade architecture and complete functionality:

• ✅ Streamable HTTP transport with session management
• ✅ Entity management, targeting, preview, upload, duplication, and validation tools connected to DV360 API
• ✅ OAuth2 service account authentication
• ✅ Rate limiting and error handling
• ✅ OpenTelemetry observability
• ✅ Dynamic entity system supporting 11 entity types
• ⚠️ Requires DV360 service account credentials (see Setup below)

MCP Tools

Entity Management (CRUD)

Tool	Description
dv360_list_entities	List entities of any type with filters and pagination
dv360_get_entity	Get a specific entity by ID
dv360_create_entity	Create a new entity
dv360_update_entity	Update an entity with updateMask discipline
dv360_delete_entity	Delete an entity

Batch Operations

Tool	Description
dv360_adjust_line_item_bids	Batch adjust bids for multiple line items
dv360_bulk_update_status	Batch update status for multiple entities
dv360_bulk_create_entities	Batch create DV360 entities
dv360_bulk_update_entities	Batch update DV360 entities

Custom Bidding Algorithms

Tool	Description
dv360_create_custom_bidding_algorithm	Create a custom bidding algorithm
dv360_manage_custom_bidding_script	Upload/manage custom bidding scripts
dv360_manage_custom_bidding_rules	Manage custom bidding rules
dv360_list_custom_bidding_algorithms	List custom bidding algorithms

Targeting

Tool	Description
dv360_list_assigned_targeting	List assigned targeting options
dv360_get_assigned_targeting	Get a specific assigned targeting option
dv360_create_assigned_targeting	Assign a targeting option
dv360_delete_assigned_targeting	Remove an assigned targeting option
dv360_validate_targeting_config	Validate a targeting configuration

Validation

Tool	Description
dv360_validate_entity	Client-side schema validation (no API call)

Key Gotchas

• Campaigns cannot be in DRAFT status (must be ACTIVE or PAUSED)
• Insertion Orders default to DRAFT status on creation
• updateMask is required for all update operations — omitting it silently ignores fields
• Rate limiting is per-advertiser (default 60 req/min)
• Entity creation requires parent IDs in a specific hierarchy

Supported Entity Types

The server supports 11 DV360 entity types through the dynamic entity system:

• Partner - DV360 partner accounts
• Advertiser - Advertiser accounts
• Campaign - Advertising campaigns
• InsertionOrder - Insertion orders (IO)
• LineItem - Line items
• AdGroup - Ad groups
• AdGroupAd - Ads within ad groups
• Creative - Creative assets
• CustomBiddingAlgorithm - Custom bidding algorithms
• InventorySource - Inventory sources
• LocationList - Geographic location lists

Authentication Modes

Mode	Header	Description
google-headers (default)	X-DV360-*	Google OAuth2 credentials via request headers
jwt	Authorization: Bearer <JWT>	JWT token authentication for hosted deployments
none	—	No authentication (development only)

Set via MCP_AUTH_MODE environment variable.

Prerequisites

• Node.js: v20 or later
• pnpm: v8 or later
• Google Cloud Project with DV360 API enabled
• Service Account with DV360 API access (see Setup Guide)

Installation

# From monorepo root
pnpm install

# Build the package
cd packages/dv360-mcp
pnpm run build

Configuration

1. Service Account Setup (Required)

Follow the detailed guide: docs/SERVICE_ACCOUNT_SETUP.md

Quick summary:

• Create GCP service account with DV360 API access
• Download service account JSON key
• Store it securely (outside the project directory)

2. Choose Your Configuration Method

Option A: Local Development (HTTP Server)

For testing with HTTP transport:

cd packages/dv360-mcp
cp .env.example .env

Edit .env and configure ONE of these credential options:

# RECOMMENDED: Path to service account JSON file
DV360_SERVICE_ACCOUNT_FILE=/absolute/path/to/service-account.json

# OR: Base64-encoded credentials
DV360_SERVICE_ACCOUNT_JSON=<base64-encoded-json>

# OR: GCP Secret Manager (production)
SERVICE_ACCOUNT_SECRET_ID=projects/123/secrets/dv360-sa/versions/latest

Option B: Claude Desktop Integration (Recommended)

For using with Claude Desktop, configure via Claude Desktop settings:

See docs/CLAUDE_DESKTOP_SETUP.md for complete instructions.

Quick configuration:

{
  "mcpServers": {
    "dv360-mcp-local": {
      "command": "node",
      "args": ["/absolute/path/to/packages/dv360-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/packages/dv360-mcp",
      "env": {
        "NODE_ENV": "development",
        "DV360_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json"
      }
    }
  }
}

Why file-based credentials?

• ✅ Most secure for local development
• ✅ Easy to rotate and manage
• ✅ Standard Google Cloud practice
• ✅ No risk of committing secrets

Development

Start Development Server

# Option 1: Using dev-server script (from repo root)
./scripts/dev-server.sh dv360-mcp

# Option 2: Direct command
cd packages/dv360-mcp
pnpm run dev:http

Server starts on http://localhost:3002

Available Scripts

pnpm run dev:http          # Start with hot reload
pnpm run build             # Build TypeScript
pnpm run typecheck         # Type checking
pnpm run generate:schemas  # Regenerate DV360 schemas from API
pnpm run test              # Run tests (when implemented)

Testing the Server

Health Check:

curl http://localhost:3002/health

MCP Endpoint:

curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Production Deployment

The server is containerized and ready for Cloud Run deployment:

# Build Docker image
docker build -t dv360-mcp .

# Run locally
docker run -p 3002:3002 --env-file .env dv360-mcp

For production deployment via Cloud Run, see root-level Terraform configuration.

Architecture

Key Components

• src/index.ts - Entry point, starts HTTP server
• src/config/ - Environment configuration
• src/container/ - Dependency injection setup (tsyringe)
• src/mcp-server/server.ts - MCP server creation
• src/mcp-server/transports/streamable-http-transport.ts - Streamable HTTP transport layer
• src/mcp-server/tools/ - MCP tool definitions
• src/services/dv360/ - DV360 API client service
• src/generated/schemas/ - Auto-generated TypeScript types and Zod schemas

Schema Generation

The server uses auto-generated schemas from the DV360 OpenAPI specification:

pnpm run generate:schemas

This generates:

• src/generated/schemas/types.ts - TypeScript types (1,962 lines)
• src/generated/schemas/zod.ts - Zod validation schemas (1,874 lines)

The schemas provide 80% size reduction from the original Discovery Document (932KB → 185KB).

Documentation

Comprehensive documentation available in docs/:

• CLAUDE_DESKTOP_SETUP.md - Claude Desktop integration guide ⭐
• SERVICE_ACCOUNT_SETUP.md - GCP service account setup
• ARCHITECTURE.md - Detailed architecture overview
• DYNAMIC_ENTITY_SYSTEM.md - Entity mapping system
• ENTITY-EXAMPLES-INTEGRATION.md - Usage patterns
• OPENTELEMETRY-IMPLEMENTATION.md - Observability setup

Troubleshooting

Authentication Errors

"DV360 service account credentials not configured"

Check which credential option you're using:

# For file-based credentials
cat /path/to/service-account.json | jq .

# For base64 credentials
echo $DV360_SERVICE_ACCOUNT_JSON | base64 -d | jq .

# For Claude Desktop, check the logs
tail -50 ~/Library/Logs/Claude/mcp-server-dv360-mcp-local.log | grep -E "config|SERVICE_ACCOUNT"

Verify API access:

• Ensure DV360 API is enabled in GCP project
• Verify service account has display-video scope
• Check service account has access in DV360 partner/advertiser settings

Server Won't Start

Check dependencies and build:

# Install dependencies
pnpm install

# Rebuild
pnpm run build

# Test locally
node dist/index.js
# Should show: "[config] Loaded .env..." or "Loading service account from file"

API rate limiting

The server implements per-advertiser rate limiting (default: 60 requests/minute).

If hitting limits:

• Check DV360_RATE_LIMIT_PER_MINUTE in .env
• Monitor logs for rate limit warnings
• Consider batching operations using workflow tools

View logs

# Local development
pnpm run dev:http

# Production (Cloud Run)
gcloud run services logs tail dv360-mcp --region=europe-west2

Next Steps

Add Tests

The testing infrastructure is in place but tests need to be written:

# Run tests (when implemented)
pnpm run test

Enable OpenTelemetry

For production observability:

# In .env
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://your-collector/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://your-collector/v1/metrics

Contributing

See root CLAUDE.md for development guidelines, build system details, and monorepo conventions. See the root README for full architecture context.

Get Started

Self-host: Follow the deployment guide to run this server on your own infrastructure.

Cesteral Intelligence: Request access -- governed execution with credential brokering, approvals, audit, and multi-tenant access.

Book a workflow demo: See it in action with your own ad accounts.

Compare options: OSS connectors vs Cesteral Intelligence

License

Apache License 2.0 — see LICENSE for details. This package is part of Cesteral's open-source connector layer; managed hosting and higher-level governance features live outside this repository.