Google Ads Model Context Protocol (MCP) Server

This is a Model Context Protocol (MCP) server that enables AI assistants (such as Gemini, ChatGPT, Claude, and Cursor) to manage, report, and analyze Google Ads campaigns securely.

It features an encrypted database storage for managing multiple client accounts, real-time Google Ads API integrations, and robust audit trail logging.

---

Features

• Campaign Reporting: Query campaigns, budgets, keywords, search terms, ads, conversions, audience, and device performance metrics.
• Campaign Mutations: Create campaigns, update budgets (with dry-run support), pause/resume campaigns, and add keywords or negative keywords.
• Account Diagnostics: Automated account analysis to identify issues like budget constraints and list actionable optimization recommendations.
• Cross-Client Performance Comparison: Compare metrics (Clicks, Cost, Conversions, CPA, ROAS) across all client accounts connected to the agency.
• Encrypted Multi-Client Credentials: Securely store and encrypt OAuth refresh tokens in Supabase using AES-256-GCM.
• Dual Transport Mode: Supports local command-line execution (stdio) and cloud-ready hosting (Streamable HTTP / SSE).
• Comprehensive Audit Trails: Automatically logs every tool execution (reads and writes) to Supabase for enterprise compliance.

---

Setup & Local Development

1. Installation

Clone the repository and install dependencies:

npm install

2. Configure Environment Variables

Copy .env.example to a new file named .env and fill in your keys:

MOCK_MODE=false

# Supabase Configurations
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-service-role-key
ENCRYPTION_KEY=your-32-character-encryption-key-here

# Google Ads API Credentials (from Google Cloud Console & Ads Manager Account)
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret
GOOGLE_DEVELOPER_TOKEN=your-google-ads-developer-token

Note: Set MOCK_MODE=true to test the server with simulated in-memory data without requiring Google Ads API credentials.

3. Generate OAuth Refresh Token

To allow the server to access a client's Google Ads account, run the OAuth helper script:

npx tsx src/utils/authHelper.ts

1. Click the generated link to open the browser.
2. Sign in with the client's Google account and grant Google Ads permissions.
3. The script will output a Refresh Token in your terminal.

4. Register a Client

Save and encrypt the client's details in your Supabase database:

npx tsx src/utils/registerClient.ts <google_customer_id> "<client_name>" "<refresh_token>"

Example:

npx tsx src/utils/registerClient.ts 181-756-0637 "nexusdatabase" "1//0gL0Srx..."

---

Running the Server

Stdio Mode (Default Local)

To run the server locally on your machine (for Cursor, Claude Desktop, or Gemini CLI):

# Build TypeScript
npm run build

# Start server
npm start

Remote / Cloud Mode (Streamable HTTP / SSE)

Whenever a PORT environment variable is defined, the server will automatically start as a web server listening on /mcp.

$env:PORT="8080"
npm start

The server will now be accessible at http://0.0.0.0:8080/mcp.

---

Testing

Run the automated mock test suite to verify that all reporting, mutation, diagnostics, and database functions are working correctly:

npm test

---

Cloud Deployment

You can host this server on any cloud platform supporting Node.js (e.g., Render, Railway, or Heroku).

1. Connect this repository to your hosting provider.
2. Configure the following deployment commands:
   • Build Command: npm install && npm run build
   • Start Command: npm start
3. Add your environment variables (from .env) in your cloud provider's dashboard.
4. Connect your AI client (like Cursor or ChatGPT) directly using the hosted URL (e.g. https://your-app-name.render.com/mcp).