MCP Marketing Analytics

A minimal MCP server for marketing analytics data discovery and querying, starting with a Google Ads integration layer.

Features

• Data source discovery
• Google Ads account discovery
• Field discovery for metrics and dimensions
• Data query execution with mock fallback and real Google Ads support when configured

Local setup

1. Install dependencies:

   npm install
   

2. Copy the environment template:

   cp .env.example .env
   

3. Build the project:

   npm run build
   

4. Start the server:

   npm start
   

Testing with MCP Inspector

Run the inspector against the local server:

npx @modelcontextprotocol/inspector node dist/server.js

Example tool calls

Health check:

{
  "name": "health_check",
  "arguments": {}
}

Discover sources:

{
  "name": "data_source_discovery",
  "arguments": {
    "search": "google"
  }
}

Discover accounts:

{
  "name": "accounts_discovery",
  "arguments": {
    "source": "AW"
  }
}

Discover fields:

{
  "name": "field_discovery",
  "arguments": {
    "source": "AW",
    "search": "cost"
  }
}

Run a query:

{
  "name": "data_query",
  "arguments": {
    "source": "AW",
    "accounts": ["1234567890"],
    "fields": ["date", "campaign_name", "clicks", "cost"],
    "dateRange": {
      "start": "2026-07-01",
      "end": "2026-07-07"
    },
    "filters": ["clicks > 100"]
  }
}

Retrieve query result:

{
  "name": "get_query_results",
  "arguments": {
    "scheduleId": "schedule-123"
  }
}

Google Ads configuration

Public multi-tenant connector

Production uses OAuth per user. The service keeps only its Google Ads developer token and Google OAuth application credentials in Vercel; each user's Google refresh token is encrypted and stored separately in Supabase. See docs/multi-tenant-oauth.md for database migration, redirect URI, environment configuration, and rollout instructions.

Local single-user mode

To enable the real Google Ads API flow, define these environment variables in your .env file:

GOOGLE_ADS_DEVELOPER_TOKEN=
GOOGLE_ADS_CLIENT_ID=
GOOGLE_ADS_CLIENT_SECRET=
GOOGLE_ADS_REFRESH_TOKEN=
GOOGLE_ADS_CUSTOMER_ID=
GOOGLE_ADS_LOGIN_CUSTOMER_ID=
GOOGLE_ADS_API_VERSION=v25
GOOGLE_ADS_MOCK_MODE=false

OAuth 2.0 setup for Google Ads

1. Create or select a Google Cloud project.
2. Enable the Google Ads API in the Google Cloud console.
3. Create OAuth 2.0 Client ID credentials for a desktop application.
4. Add the following OAuth scopes to the consent screen:
   • https://www.googleapis.com/auth/adwords
5. Use a redirect URI such as:
   • http://localhost
6. Complete the OAuth authorization flow and store the generated refresh token in GOOGLE_ADS_REFRESH_TOKEN.
7. Insert your Google Ads developer token and customer IDs in the environment variables above.

Recommended values for the environment file

• GOOGLE_ADS_DEVELOPER_TOKEN: your Google Ads manager/developer token.
• GOOGLE_ADS_CLIENT_ID: OAuth client ID from Google Cloud.
• GOOGLE_ADS_CLIENT_SECRET: OAuth client secret from Google Cloud.
• GOOGLE_ADS_REFRESH_TOKEN: refresh token obtained after the OAuth flow.
• GOOGLE_ADS_CUSTOMER_ID: the Google Ads customer ID you want to query.
• GOOGLE_ADS_LOGIN_CUSTOMER_ID: the manager/customer ID used for login context, often the same as the customer ID.
• GOOGLE_ADS_API_VERSION: Google Ads API version; defaults to v25.
• GOOGLE_ADS_MOCK_MODE: opt-in demo data mode; keep false for the real integration.

Local OAuth helper

A local helper is now included so you can complete the flow directly from this project.

1. Make sure your .env contains GOOGLE_ADS_CLIENT_ID and GOOGLE_ADS_CLIENT_SECRET.
2. Build the project:

   npm run build
   

3. Start the OAuth helper:

   npm run oauth:google-ads
   

4. Open the printed URL in your browser, approve the consent screen, and return to the terminal.
5. The helper will exchange the authorization code for tokens and print the response.

Example OAuth flow

If you want to test the flow manually, use the standard OAuth 2.0 desktop-app flow:

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/adwords&prompt=consent

Then exchange the returned authorization code for a refresh token using the local helper above.

Important notes

• The Google Ads API requires a valid developer token and OAuth credentials.
• The current implementation uses mock data whenever the required credentials are missing.
• Once the credentials are present, the server will attempt to call the real Google Ads API endpoints.

Connection diagnostics

Use the google_ads_connection_status MCP tool to verify production configuration without returning credential values. Missing credentials now produce a clear error; mock responses are used only when GOOGLE_ADS_MOCK_MODE=true.