WPP-mcp-servers by dogancanbaris - MCP Server

WPP Marketing Analytics Platform - MCP Servers

Enterprise-grade Model Context Protocol servers with Router + Backend architecture, connecting AI agents to 7 Google Marketing APIs with OAuth 2.0 authentication, interactive workflows, automated dashboards, and multi-tenant support.

🎯 What This Is

A production-ready MCP server system providing 102 interactive tools across:

Google Search Console (8 tools) - Organic search analytics
Google Ads (60 tools) - Comprehensive campaign management and reporting
Google Analytics 4 (11 tools) - User behavior tracking
BigQuery (3 tools) - Data warehouse queries
Business Profile (3 tools) - Local SEO management
CrUX/Core Web Vitals (5 tools) - Performance monitoring
WPP Analytics Platform (9 tools) - Dashboard creation
SERP API (1 tool) - Search results tracking
Dashboard Tools (2 tools) - Integration and data management

🚀 BREAKTHROUGH: Meta-Tools Architecture (v2.2)

Architecture:

Client (Claude Code CLI)
    ↓ stdio
MCP Router (~2K tokens - 3 meta-tools only!)
    ↓ On-demand HTTP (localhost:3100)
Google Backend Server (98 tools, never loaded)

Why Meta-Tools:

97% token reduction: 2K tokens loaded (vs 65K traditional)
On-demand discovery: Tools found via search_tools, not listed upfront
Infinite scalability: Can support 500+ tools with same 2K token budget
Interactive workflows: Full guided parameter discovery preserved
Proven: Tool schemas verified to NOT enter context via /context measurements

Server Modes:

Router (stdio): npm run dev:router - For Claude Code CLI (minimal tokens)
Backend (HTTP): npm run dev:google-backend - Port 3100 (all 66 tools)
Legacy HTTP: npm run dev:http - Port 3001 (OMA integration, monolithic)

Token Usage:

Meta-tools mode (v2.2): ~2,000 tokens (97% reduction) ← Current!
Router mode (v2.1): ~6,000 tokens (94% reduction)
HTTP mode (legacy): ~5,000 tokens
Monolithic mode (v2.0): ~104,000 tokens

📘 - Complete reference for MCP tool usage

🚀 Quick Start

For Practitioners (Using MCP)

# Verify MCP server is available
/mcp

# Try your first query
"Show me my Google Search Console properties"

# Use Claude agent skills for workflows
"Create SEO dashboard for my client"

→ See

For Developers (Router Architecture)

# Clone and setup
git clone <repo>
cd "MCP Servers"
npm install

# Configure OAuth & backends
cp .env.router.example .env.router
# Edit .env.router with your credentials

# Build
npm run build

# Option 1: Router Mode (Recommended - 94% token reduction)
# Terminal 1: Start Google backend
npm run dev:google-backend  # Port 3100

# Terminal 2: Start router (use in Claude Code CLI)
npm run dev:router  # stdio transport

# Option 2: Legacy HTTP Mode (for OMA integration)
ENABLE_DEV_BYPASS=true npm run dev:http  # Port 3001
# Health check: curl http://localhost:3001/health

→ See → See

📚 Complete Documentation

All documentation is organized in /docs:

Section	Purpose	Key Docs
OAuth	Authentication & token handling	,
Reporting	Dashboard builder & visualizations	,
Guides	Architecture, tools, workflows	,
Chrome DevTools	Browser automation in WSL2	,

→

🔑 Key Features

✅ Router + Backend Architecture - Modular, scalable multi-platform design ✅ 94% Token Reduction - 6K tokens loaded (vs 104K monolithic) ✅ Interactive Workflows - Tools guide users step-by-step through parameters ✅ 102 Production Tools - Ready to use across 7 Google APIs (60 for Google Ads) ✅ OAuth 2.0 Only - No API keys or service accounts, per-request auth ✅ Multi-Tenant Ready - Automatic client isolation via user credentials ✅ Multi-Step Approval - WRITE operations require confirmation with impact preview ✅ 9-Layer Safety System - Approval workflows, snapshots, audit logging ✅ On-Demand Guidance - Rich insights injected in responses (not loaded upfront) ✅ Dashboard Builder - Create professional reports in 5 tool calls ✅ Real-Time Data - Live analytics from Google platforms ✅ BigQuery Integration - Powerful data blending and analysis

💻 Tech Stack

Backend (Router Architecture):

Node.js 18+ with TypeScript 5.3
MCP Router (stdio transport, minimal token usage)
HTTP Backend Servers (Express with SSE, tool execution)
Interactive Workflow System (parameter discovery, guidance injection)
OAuth 2.0 per-request authentication
BigQuery for data warehouse
Multi-step approval system with dry-run previews

Frontend (Dashboard):

Next.js 15 + React 19
ECharts 5.6 (primary) + Recharts 3.3 (secondary)
32 chart types + 12 controls
Supabase for authentication & RLS
Zustand for state management

Infrastructure:

Google Cloud Platform
BigQuery for analytics
Supabase for dashboard storage

🏗️ Architecture

Router Pattern (v2.1 - Current):

Claude Code CLI
    ↓ stdio
MCP Router (Port N/A)
    ├── Minimal tool descriptions (~15 tokens/tool)
    ├── Backend registry & routing
    └── Tool call forwarding
         ↓ HTTP (localhost:3100)
Google Backend Server
    ├── 66 tools (all Google platforms)
    ├── OAuth token handling
    ├── Interactive workflows
    ├── Approval enforcement
    └── Audit logging
         ↓ HTTPS
Google Cloud APIs
    ├── Search Console API
    ├── Google Ads API
    ├── Analytics API
    ├── BigQuery API
    └── Business Profile API
         ↓
BigQuery Data Lake + Dashboard Platform

Connection Flow (Router Mode):

Client → Router (stdio) → tools/list → 66 tools with minimal descriptions
Client → Router → tools/call(tool_name) → Router forwards to backend HTTP
Backend → Executes tool with OAuth → Returns rich response with guidance
Router → Returns response to client → Client sees formatted results + next steps

Connection Flow (Legacy HTTP Mode for OMA):

Agent → POST /mcp (initialize) → Get session ID
Agent → POST /mcp (tools/list) → See 66 tools
Agent → POST /mcp (tools/call) → Execute tool
MCP Server → Google APIs (with user OAuth token)
Response → Agent

🔐 Security & Multi-Tenancy

User OAuth Tokens: Each user uses their own Google credentials
Automatic Isolation: Google IAM enforces data access control
Zero Provisioning: No manual per-user setup needed
Audit Trail: Every operation logged with user context
Token Rotation: Automatic hourly refresh

Supports 1,000+ practitioners with no per-user infrastructure!

📊 Example Workflows

1. SEO Performance Review

// Agent workflow
1. Pull GSC data via query_search_analytics
2. Analyze trends with analyze_gsc_data_for_insights
3. Create dashboard with create_dashboard_from_table
4. User views interactive dashboard

2. Campaign Optimization

// Agent workflow
1. Get Google Ads performance (get_campaign_performance)
2. Pull Search Console data (query_search_analytics)
3. Join data in BigQuery (run_bigquery_query)
4. Create comparison dashboard

3. Keyword Research

// Agent workflow
1. Generate keyword ideas (generate_keyword_ideas)
2. Get forecasts (get_keyword_forecasts)
3. Add to campaign with approval (add_keywords)
4. Track performance over time

📈 Current Status (v2.1 - October 31, 2025)

✅ 102 Interactive Tools: All production-ready with guided workflows (66 existing + 36 new Google Ads tools)
✅ Router Architecture: 94% token reduction (6K vs 104K)
✅ All 102 Tools Transformed: Patterns demonstrated and implemented across all categories
- Simple READ: 28 tools (list_properties, list_accounts, list_campaigns, etc.)
- Complex READ: 62 tools (query_search_analytics, get_performance, etc.)
- WRITE with approval: 12 tools (budget updates, keyword creation, campaign management, etc.)
✅ Interactive Workflows: Parameter discovery, rich guidance, multi-step approval, next-step suggestions
✅ HTTP Server: External server for multi-agent connections (legacy/OMA mode)
✅ OAuth: 100% implemented (per-request auth, no service accounts)
✅ Dashboard Platform: Full-featured with 32 chart types + 12 controls
✅ Safety System: 9-layer protection complete + enhanced dry-run previews
✅ Documentation: Comprehensive and organized
✅ Compilation: 0 errors, 0 warnings
✅ Tested: Router + backend verified, token reduction confirmed

🎯 For Different Users

I'm a Marketer → I'm a Developer → I'm DevOps → I need to integrate OMA → I need to set up Chrome automation →

📋 Project Structure

project/
├── README.md                          ← You are here
├── CLAUDE.md                          ← AI agent guide + quick reference
├── PROJECT-BLUEPRINT.md               ← Complete project manual
├── docs/                              ← All documentation
│   ├── router-architecture.md         ← Router implementation guide
│   ├── mcp-architecture-recommendations.md  ← Architecture decisions
│   ├── SESSION-HANDOVER-interactive-tool-transformation.md  ← Transformation log
│   ├── oauth/                         ← OAuth guides
│   ├── reporting-platform/            ← Dashboard docs
│   ├── guides/                        ← Developer guides
│   └── chrome-devtools/               ← Browser automation
├── src/                               ← TypeScript source
│   ├── router/                        ← MCP Router (stdio, minimal tokens)
│   │   ├── server.ts                  ← Router entry point
│   │   ├── backend-registry.ts        ← Backend management, description extraction
│   │   ├── http-client.ts             ← HTTP client for backends
│   │   ├── config.ts                  ← Environment configuration
│   │   └── types.ts                   ← TypeScript interfaces
│   ├── backends/                      ← HTTP Backend Servers
│   │   └── google-marketing/          ← Google backend (port 3100, 66 tools)
│   ├── shared/                        ← Shared utilities
│   │   ├── interactive-workflow.ts    ← NEW: Interactive workflow utilities
│   │   ├── oauth-client-factory.ts    ← OAuth clients
│   │   ├── approval-enforcer.ts       ← Multi-step approval
│   │   └── logger.ts                  ← Structured logging
│   ├── ads/                           ← Google Ads tools (25 tools)
│   ├── gsc/                           ← Search Console tools (8 tools)
│   ├── analytics/                     ← Analytics tools (11 tools)
│   ├── bigquery/                      ← BigQuery tools (3 tools)
│   ├── business-profile/              ← Business Profile tools (3 tools)
│   ├── crux/                          ← Core Web Vitals tools (5 tools)
│   ├── wpp-analytics/                 ← Dashboard tools (9 tools)
│   ├── serp/                          ← SERP API tools (1 tool)
│   └── http-server/                   ← Legacy HTTP server (OMA mode)
├── .env.router.example                ← Router environment template
├── dist/                              ← Compiled JavaScript
├── tests/                             ← Test files
├── package.json                       ← NPM scripts
└── tsconfig.json                      ← TypeScript config

🚀 Getting Started

Read: or
Install: Node.js 18+, npm
Configure: OAuth credentials + HTTP settings in .env
Build: npm run build
Run: ENABLE_DEV_BYPASS=true npm run start:http
Test: curl http://localhost:3000/health
Connect: Agents use http://localhost:3000/mcp endpoint
Use Tools: See

🔗 Important Links

Complete Docs:
AI Agent Guide: - START HERE for AI agents
Router Architecture:
Interactive Workflows:
OAuth Setup:
Dashboard Platform:
Tech Reference:

❓ FAQ

Q: Do I need service accounts? A: No! OAuth 2.0 handles everything. Users authenticate with their Google account.

Q: How is data isolated between users? A: Automatically via Google IAM. User A's OAuth token can only access User A's data.

Q: What's the cost? A: ~$11-38/month for infrastructure. BigQuery first 1TB/month is free.

Q: Can I integrate with OMA? A: Yes! The HTTP server is specifically designed for OMA integration. See for native tool mounting, or for architecture details.

Q: How many users can it support? A: Unlimited. OAuth per-request + HTTP architecture scales infinitely with multiple concurrent connections.

Q: How do agents connect? A: Via HTTP endpoint http://localhost:3000/mcp - see the or

📞 Support

Documentation: See
Issues: Check troubleshooting in relevant guide
Code Questions: Review code comments and type definitions

📄 License

Status: ✅ Production Ready - Router + Backend Architecture Version: 2.1 Tools: 102 across 7 Google APIs (all with interactive workflows, October 31, 2025) Architecture: Router (stdio) + HTTP Backends Transport: STDIO (router) / HTTP (backends) / HTTP (legacy OMA mode) Auth: OAuth 2.0 per-request (100%) Token Usage: ~6k tokens router mode (94% reduction), ~5k tokens HTTP mode Interactive Workflows: ✅ Parameter discovery, rich guidance, multi-step approval (all 102 tools) Google Ads Tools: 60 comprehensive tools (campaigns, keywords, budgets, bidding, targeting, reporting, audiences, labels, conversions) Last Updated: October 31, 2025