ads-setup

Set up ad platform accounts and connect via MCP. Walks you through Google Ads, Meta Ads, or Apple Search Ads from scratch, including account creation, API credentials, MCP server installation, and connection verification. Use when: "/ads-setup", "set up google ads", "connect ads to claude", "MCP setup", "ads account setup", "connect meta ads", "connect apple search ads", "ads MCP".

Ads Setup Guide

You are walking the user through ad platform setup from scratch. This covers two parts: creating ad accounts (if needed) and connecting them to Claude via MCP.

Start by asking two questions:

Question A: Do you already have an ad account on your chosen platform(s)?

  • Yes, I have active ad accounts
  • No, I need to create one from scratch
  • I have an account but haven't run ads yet

Question B: Do you already have your ad platform connected via MCP?

  • Yes, it's already set up and working
  • No, I need help setting it up from scratch
  • I'm not sure what MCP is

If they need the MCP explainer: MCP (Model Context Protocol) is a pipe that lets Claude pull live data from external services like Google Ads. Think of it as giving Claude read (and optionally write) access to your ad account through the official API. You install a small server locally, give it your API credentials, and Claude can then query your campaigns directly.

Based on their answers, jump to the relevant section(s) below.

SECTION A: CREATING AD ACCOUNTS FROM SCRATCH

Only show the relevant platform(s).

CREATING A GOOGLE ADS ACCOUNT

Prerequisites

  • A Google account (Gmail or Google Workspace). If they don't have one: go to accounts.google.com > "Create account"
  • A payment method (credit card, debit card, or bank account)
  • A website or app to advertise (even a landing page works)

Step-by-Step Account Creation

Step 1: Go to ads.google.com

Step 2: Choose Your Campaign Goal Google will try to push you into creating a campaign immediately. You have two paths:

  • Path A (Recommended): Skip the campaign setup

    • At the bottom of the screen, look for "Switch to Expert Mode" or "Create an account without a campaign"
    • This lets you set up the account without committing to spend yet
    • You can always create campaigns later

  • Path B: Create a campaign during setup

    • Pick a goal (Sales, Leads, Website traffic, etc.)
    • Google walks you through campaign creation
    • You can pause it immediately after setup to avoid spending

Step 3: Set Your Billing Country and Currency

  • Pick your country and currency. WARNING: You CANNOT change these later.
  • Time zone also cannot be changed. Pick carefully.

Step 4: Add Billing Information

  • Enter your payment method
  • Google may charge a small verification amount (refunded)
  • You can set a budget limit to avoid surprise charges

Step 5: (Recommended) Create a Manager Account (MCC) For API access and to manage multiple accounts:

  1. Go to https://ads.google.com/home/tools/manager-accounts/
  2. Click "Create a manager account"
  3. Enter a name (e.g., "My Ads MCC")
  4. Link your regular ad account to the MCC
  5. The MCC gives you access to the API Center where you get your Developer Token

Step 6: Set Up Conversion Tracking Before running any campaigns, set up tracking:

  1. In Google Ads, go to Tools & Settings > Measurement > Conversions
  2. Click "+ New conversion action"
  3. Choose "Website" (most common)
  4. Install the Google tag on your website (or use Google Tag Manager)
  5. Define what counts as a conversion (purchase, signup, form submission, etc.)

Ask: "Is your Google Ads account created? Can you see the dashboard at ads.google.com?"

CREATING A META (FACEBOOK/INSTAGRAM) ADS ACCOUNT

Prerequisites

  • A personal Facebook account (required even for business use)
  • A Facebook Business Page for your business
  • A payment method

Step-by-Step Account Creation

Step 1: Create a Facebook Business Page (if you don't have one)

  1. Go to https://www.facebook.com/pages/create
  2. Choose a category (Business, Brand, Community, etc.)
  3. Fill in your business name and description
  4. Add a profile photo and cover image
  5. You need this page to run ads. It's what shows as the "advertiser."

Step 2: Set Up Meta Business Suite (formerly Business Manager)

  1. Go to https://business.facebook.com/
  2. Click "Create Account" (or "Get Started")
  3. Enter your business name, your name, and business email
  4. This is the hub where you manage everything: ad accounts, pages, pixels, team members

Step 3: Create an Ad Account

  1. In Business Suite, go to Settings (gear icon) > Business Settings
  2. Click Accounts > Ad Accounts
  3. Click "Add" > "Create a new ad account"
  4. Name it (e.g., "Main Ad Account")
  5. Set your currency and time zone. WARNING: Cannot be changed later.
  6. Assign it to your business
  7. Add yourself as an Admin

Step 4: Add a Payment Method

  1. In Business Settings > Payment Methods
  2. Click "Add Payment Method"
  3. Enter credit card, PayPal, or bank account details
  4. Link this payment method to your ad account

Step 5: Install the Meta Pixel This is how Meta tracks conversions on your website:

  1. In Business Suite, go to Events Manager (or Data Sources > Pixels)
  2. Click "Add" > "Connect Data Sources" > "Web"
  3. Name your pixel
  4. Choose installation method:
    • Partner Integration: If you use Shopify, WordPress, etc., pick your platform and follow the steps
    • Manual Install: Copy the pixel code and paste it in your website's <head> tag
    • Google Tag Manager: Use Meta's GTM integration
  5. Set up events (ViewContent, AddToCart, Purchase, Lead, etc.)
  6. Use the Meta Pixel Helper Chrome extension to verify it's working

Step 6: Verify Your Domain

  1. In Business Settings > Brand Safety > Domains
  2. Add your domain
  3. Verify it via DNS TXT record, HTML file upload, or meta tag
  4. This is required for proper conversion tracking and ad performance

Ask: "Is your Meta Ads account set up? Can you access Ads Manager at https://adsmanager.facebook.com/?"

CREATING AN APPLE SEARCH ADS ACCOUNT

Prerequisites

Step-by-Step Account Creation

Step 1: Go to Apple Search Ads

  1. Go to https://searchads.apple.com/
  2. Click "Start Now" or "Sign In" with your Apple ID

Step 2: Choose Your Plan

Apple offers two tiers:

  • Search Ads Basic (simpler, automated)

    • Apple handles targeting and bidding automatically
    • You set a budget and a target CPI (cost per install)
    • Limited reporting and no keyword-level control
    • Good for beginners, but NOT enough for the autopilot skill (no API access)

  • Search Ads Advanced (full control) -- Choose this one

    • Full keyword-level targeting and bidding
    • Detailed reporting (search terms, demographics, etc.)
    • API access for automation
    • Required for MCP integration

Click "Start Using Search Ads Advanced"

Step 3: Set Up Your Account

  1. Accept the Apple Search Ads terms and conditions
  2. Enter your billing information (credit card)
  3. Set your currency and time zone
  4. Set a daily budget cap for your account (you can change this later)

Step 4: Add Your App

  1. In the dashboard, click "Create Campaign"
  2. Search for your app by name or App Store ID
  3. Select it. Only apps you own or have admin access to will appear.
  4. If your app doesn't show up:
    • Make sure you're using the same Apple ID that's the Account Holder or Admin in App Store Connect
    • The app must be live and published, not in review or draft

Step 5: Create Your First Campaign

  1. Choose campaign type: "Search Results" (main placement) or "Search Tab" (exploratory)
  2. Select countries/regions to target
  3. Set a daily budget
  4. Create an ad group with keywords you want to target
  5. You can pause the campaign immediately after creation

Step 6: Set Up the Apple Search Ads Attribution API (for conversion tracking)

  1. If your app uses an MMP (AppsFlyer, Adjust, Branch, etc.), connect it in App Store Connect
  2. If not, implement the AdServices framework in your app:
    • In Xcode, add the AdServices framework
    • Call AAAttribution.attributionToken() on first launch
    • Send the token to Apple's attribution API to get conversion data
  3. This tells you which keywords and search terms drove installs

Step 7: Set Up API Access (needed for MCP)

  1. In Search Ads, go to Settings > API
  2. Click "Create API Certificate"
  3. Download the private key (.pem file). Store it safely, you can only download it once.
  4. Note your Client ID, Team ID, and Key ID
  5. You'll need these for the MCP setup in Section B below

Ask: "Is your Apple Search Ads Advanced account set up? Can you see the campaign dashboard at searchads.apple.com?"

SECTION B: MCP SETUP (Connecting Your Ad Account to Claude)

Now that the ad account exists, connect it to Claude via MCP.

GOOGLE ADS MCP SETUP

Step 1: Choose Your MCP Server

Ask the user:

Which level of access do you need?

  • Read-only (can pull data, can't make changes) -- Recommended to start
  • Read + Write (can also add negative keywords, change budgets, etc.)

Option A: Read-Only (Google's Official Server)

  • Repo: github.com/googleads/google-ads-mcp
  • 2 tools: search (runs any GAQL query) and list_accessible_customers
  • Safest option. Good enough for analysis and reporting.

Option B: Read + Write (Community Server, 29 tools)

  • Repo: github.com/itallstartedwithaidea/google-ads-mcp
  • 9 read tools, 7 audit tools, 11 write tools, 2 docs tools
  • Dry-run mode by default (write operations show what WOULD happen without doing it)
  • This is closest to Austin Lau's setup at Anthropic

Step 2: Get Google Ads API Credentials

Walk through each sub-step. Confirm after each one.

2a. Google Ads Developer Token

  1. Go to ads.google.com and sign in
  2. Click the wrench icon (Tools & Settings) > Setup > API Center
  3. If you don't see API Center, you need a Manager (MCC) account. Go to ads.google.com/home/tools/manager-accounts/ to create one, then link your ad account to it
  4. In API Center, apply for a Developer Token. For testing/personal use, you'll get a test token immediately. For production access, you'll need to fill out the application (takes 1-3 business days)
  5. Copy the Developer Token

Ask: "Do you have your Developer Token? Paste it here (or just confirm you have it, I won't store it in chat)."

2b. Google Cloud OAuth Credentials

  1. Go to console.cloud.google.com
  2. Create a new project (or use existing). Name it something like "Claude Ads Manager"
  3. Go to APIs & Services > Library
  4. Search for "Google Ads API" and click Enable
  5. Go to APIs & Services > Credentials
  6. Click "Create Credentials" > "OAuth client ID"
  7. If prompted, configure the OAuth consent screen first:
    • User Type: External (or Internal if using Google Workspace)
    • App name: "Claude Ads Manager" (or whatever you want)
    • Scopes: Add https://www.googleapis.com/auth/adwords
    • Test users: Add your own email
  8. Back in Credentials, create OAuth client ID:
    • Application type: "Desktop app"
    • Name: "Claude Ads MCP"
  9. Download the JSON file or copy the Client ID and Client Secret

Ask: "Do you have your Client ID and Client Secret?"

2c. Get a Refresh Token This is the trickiest part. Walk through it:

  1. Install the Google Auth library:

    pip install google-auth-oauthlib

  2. Run this Python script:

    from google_auth_oauthlib.flow import InstalledAppFlow

flow = InstalledAppFlow.from_client_config(
    {
        "installed": {
            "client_id": "YOUR_CLIENT_ID",
            "client_secret": "YOUR_CLIENT_SECRET",
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    },
    scopes=["https://www.googleapis.com/auth/adwords"],
)
creds = flow.run_local_server(port=0)
print(f"Refresh Token: {creds.refresh_token}")

  3. A browser window will open. Sign in with the Google account that has access to your Google Ads

  4. Copy the Refresh Token that prints in the terminal

Ask: "Did you get the Refresh Token?"

2d. Find Your Customer ID

  1. Go to ads.google.com
  2. Your Customer ID is in the top right corner (format: XXX-XXX-XXXX)
  3. If you're using an MCC, you need BOTH the MCC ID (login customer ID) and the individual account ID

Ask: "What's your Customer ID? (and MCC ID if applicable)"

Step 3: Install the MCP Server

For Option A (Google Official, Read-Only):

# Clone the repo
git clone https://github.com/googleads/google-ads-mcp.git
cd google-ads-mcp

# Install dependencies
pip install -r requirements.txt

# Create a google-ads.yaml config file
cat > google-ads.yaml << 'EOF'
developer_token: YOUR_DEVELOPER_TOKEN
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
login_customer_id: YOUR_MCC_ID
EOF

For Option B (Read + Write):

pip install git+https://github.com/itallstartedwithaidea/google-ads-mcp.git

Step 4: Configure Claude to Use It

Add to .mcp.json in the project root (or ~/.claude/settings.json for global access):

Option A config:

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "google_ads_mcp.server"],
      "env": {
        "GOOGLE_ADS_YAML_PATH": "/path/to/your/google-ads.yaml"
      }
    }
  }
}

Option B config:

{
  "mcpServers": {
    "google-ads": {
      "command": "python",
      "args": ["-m", "ads_mcp.server"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MCC_ID",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

Step 5: Verify Connection

After configuring, restart Claude Code and test with:

  • "List my Google Ads accounts" (should use list_accessible_customers)
  • "Show my top 5 campaigns by spend this month" (should run a GAQL query)

If it fails, check:

  1. Is the Developer Token approved? (Test tokens only work with test accounts)
  2. Is the Google Ads API enabled in Google Cloud Console?
  3. Is the Refresh Token still valid? (They expire if the OAuth consent screen is in "Testing" mode and it's been 7 days)
  4. Is the Customer ID formatted correctly? (Numbers only, no dashes)

META ADS MCP SETUP

Step 1: Choose Your MCP Server

Recommended: meta-ads-mcp by pipeboard-co

  • Repo: github.com/pipeboard-co/meta-ads-mcp
  • Tools: campaign management, ad set management, ad insights, audience targeting
  • Supports read and write operations

Alternative: meta-marketer by marccgrau

  • Repo: github.com/marccgrau/meta-marketer
  • More focused on campaign creation and optimization

Step 2: Get Meta API Credentials

2a. Create a Meta Developer App

  1. Go to developers.facebook.com
  2. Click "My Apps" > "Create App"
  3. Choose "Business" as the app type
  4. Name it "Claude Ads Manager"
  5. After creation, go to App Settings > Basic and note your App ID and App Secret

2b. Get a Long-Lived Access Token

  1. Go to developers.facebook.com/tools/explorer/
  2. Select your app from the dropdown
  3. Click "Generate Access Token"
  4. Grant these permissions:
    • ads_management (read + manage ads)
    • ads_read (read ad data)
    • business_management (if using Business Manager)
  5. Copy the short-lived token
  6. Exchange it for a long-lived token (60 days) by running: 
    curl "https://graph.facebook.com/v21.0/oauth/access_token?grant_type=fb_exchange_token&client_id=YOUR_APP_ID&client_secret=YOUR_APP_SECRET&fb_exchange_token=YOUR_SHORT_LIVED_TOKEN"
  7. Copy the long-lived access token from the response

Note: Long-lived tokens expire after 60 days. Set a reminder to refresh. For permanent access, set up a System User in Business Manager.

2c. Find Your Ad Account ID

  1. Go to business.facebook.com > Business Settings > Accounts > Ad Accounts
  2. Your Ad Account ID starts with "act_" followed by numbers
  3. Or find it in Ads Manager URL: adsmanager.facebook.com/adsmanager/manage/campaigns?act=XXXXXXXX

Ask: "Do you have your App ID, App Secret, Access Token, and Ad Account ID?"

Step 3: Install and Configure

# Install the MCP server
pip install meta-ads-mcp
# OR clone from repo
git clone https://github.com/pipeboard-co/meta-ads-mcp.git
cd meta-ads-mcp && pip install -r requirements.txt

Add to .mcp.json:

{
  "mcpServers": {
    "meta-ads": {
      "command": "python",
      "args": ["-m", "meta_ads_mcp.server"],
      "env": {
        "META_APP_ID": "YOUR_APP_ID",
        "META_APP_SECRET": "YOUR_APP_SECRET",
        "META_ACCESS_TOKEN": "YOUR_LONG_LIVED_TOKEN",
        "META_AD_ACCOUNT_ID": "act_XXXXXXXX"
      }
    }
  }
}

Step 4: Verify Connection

Test with:

  • "List my Meta ad campaigns"
  • "Show spend by campaign for the last 7 days"

If it fails, check:

  1. Is the access token still valid? (Check at developers.facebook.com/tools/debug/accesstoken/)
  2. Does the token have ads_read and ads_management permissions?
  3. Is the Ad Account ID correct and prefixed with "act_"?
  4. Is the app in Development or Live mode? (Some features require Live mode)

APPLE SEARCH ADS MCP SETUP

Step 1: Choose Your MCP Server

Recommended: apple-search-ads-mcp

  • Search GitHub for the latest community MCP server for Apple Search Ads
  • Apple Search Ads uses a REST API with OAuth 2.0

If no dedicated MCP server exists yet, we can create a lightweight one using the Apple Search Ads API directly. The skill will generate a custom MCP server script for you.

Step 2: Get Apple Search Ads API Credentials

2a. Generate API Credentials in Apple Search Ads

  1. Sign in to searchads.apple.com
  2. Go to Settings (gear icon) > API
  3. If you don't see API settings, you need Admin or Account Manager role
  4. Click "Create API Certificate" (this gives you a .pem key file)
  5. Note your:
    • Client ID
    • Team ID
    • Key ID
    • Download the private key (.pem file)

2b. Generate a Client Secret (JWT) Apple Search Ads uses JWT-based auth. You need to generate a client secret:

import jwt
import datetime

# Your credentials
TEAM_ID = "YOUR_TEAM_ID"
KEY_ID = "YOUR_KEY_ID"
CLIENT_ID = "YOUR_CLIENT_ID"

# Read your private key
with open("path/to/AuthKey.pem", "r") as f:
    private_key = f.read()

# Generate JWT
now = datetime.datetime.utcnow()
payload = {
    "sub": CLIENT_ID,
    "aud": "https://appleid.apple.com",
    "iat": now,
    "exp": now + datetime.timedelta(days=180),
    "iss": TEAM_ID,
}
headers = {"kid": KEY_ID, "alg": "ES256"}

client_secret = jwt.encode(payload, private_key, algorithm="ES256", headers=headers)
print(f"Client Secret: {client_secret}")

Install dependency first: pip install PyJWT cryptography

2c. Get an Access Token

curl -X POST "https://appleid.apple.com/auth/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_JWT_SECRET&scope=searchadsorg"

Copy the access_token from the response.

2d. Find Your Org ID

curl "https://api.searchads.apple.com/api/v5/me/acls" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response includes your orgId.

Step 3: Configure

If using a dedicated MCP server, add to .mcp.json:

{
  "mcpServers": {
    "apple-search-ads": {
      "command": "python",
      "args": ["-m", "apple_ads_mcp.server"],
      "env": {
        "APPLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "APPLE_ADS_TEAM_ID": "YOUR_TEAM_ID",
        "APPLE_ADS_KEY_ID": "YOUR_KEY_ID",
        "APPLE_ADS_PRIVATE_KEY_PATH": "/path/to/AuthKey.pem",
        "APPLE_ADS_ORG_ID": "YOUR_ORG_ID"
      }
    }
  }
}

If no MCP server exists, the skill will generate a custom lightweight one that wraps the Apple Search Ads REST API with these tools:

  • list_campaigns -- Get all campaigns with status and budget
  • get_campaign_report -- Performance metrics by campaign
  • get_keyword_report -- Keyword-level performance data
  • get_search_term_report -- Search terms triggering your ads
  • add_negative_keywords -- Block unwanted search terms
  • update_campaign_budget -- Adjust daily budgets

Step 4: Verify Connection

Test with:

  • "List my Apple Search Ads campaigns"
  • "Show keyword performance for last 7 days"

If it fails, check:

  1. Is the JWT (client secret) still valid? (They last 180 days max)
  2. Does your API user have the right role? (Admin or Account Manager needed)
  3. Is the Org ID correct?
  4. Apple Search Ads API has rate limits (20 calls per second). If you get 429 errors, the MCP server needs retry logic.

MULTIPLE PLATFORMS

If the user selected multiple platforms, install each MCP server separately. They all coexist in .mcp.json:

{
  "mcpServers": {
    "google-ads": { "..." : "..." },
    "meta-ads": { "..." : "..." },
    "apple-search-ads": { "..." : "..." }
  }
}

The skills detect which platform tools are available and use the right one. Cross-platform reporting skills can pull from all connected platforms and combine the data.

TROUBLESHOOTING COMMON ISSUES

Walk the user through these if they get stuck:

  1. "MCP server not found" -- The Python package isn't installed or isn't in PATH. Try which python and make sure it's the same Python where you installed the package. Consider using full path: /usr/local/bin/python3

  2. "Authentication failed" -- Most common issue. Tokens expire. Refresh tokens can be revoked if OAuth consent screen is in Testing mode (Google). Long-lived tokens expire after 60 days (Meta). JWTs expire after 180 days (Apple).

  3. "Permission denied" -- Your API credentials don't have the right scopes/permissions. Re-check the permissions granted during OAuth flow.

  4. "Rate limited" -- All platforms have rate limits. The MCP servers should handle this with exponential backoff, but if not, space out your queries.

  5. "No data returned" -- Check your date range and customer/account ID. Test accounts return empty data. Make sure you're querying the right account.