# Marketing MCP

One MCP server that combines Google Ads (keyword research, GAQL reporting, and
campaign management), Meta Ads, GA4, Google Search Console, and a no-setup
SEO/site toolkit (on-page audit, site crawl, broken-link and structured-data
checks, technical-health check, PageSpeed, one-number score), plus a multi-client
rollup. Works with Claude Desktop and Claude Code.
Each platform is independent: a tool returns a clear "needs setup" note until its
credentials are present, and several tools work with no setup at all.

## Install

**macOS / Linux** (needs Python 3.10+; on macOS `brew install python@3.11`):

```
git clone https://github.com/Jluethke/marketing-mcp.git
cd marketing-mcp
bash install.sh
```

**Windows** (needs Python 3.10+ from python.org):

```
git clone https://github.com/Jluethke/marketing-mcp.git
cd marketing-mcp
install.bat
```

The installer creates a `.venv`, installs the dependencies, and registers
`marketing-mcp` into your Claude config (Claude Desktop if installed, and Claude
Code). Restart Claude so it loads the server.

To register without the installer (you already have a venv or Python):
`python register.py`.

## Try it now (no setup)

These tools work the moment the server is installed, with no accounts or keys.
Start here to confirm it runs, before connecting anything:

- `seo_score` — paste a URL, get one 0-100 health score and letter grade with the
  top fixes. The fastest "how's this page doing". Try: "seo_score for https://example.com".
- `seo_audit` — full on-page audit (title, meta, headings, word count, links,
  images missing alt, issues). Try: "seo_audit for https://example.com".
- `crawl_site` — crawl up to N pages and aggregate the most common issues across
  the site (the multi-page version of seo_audit).
- `check_links` — find broken (4xx/5xx) links on a page.
- `content_analysis` — Flesch readability, keyword density, heading outline; pass a
  focus keyword to see where it appears.
- `http_check` — redirect chain, HTTPS, security headers, response time, mixed content.
- `validate_schema` — open the page's JSON-LD and flag missing recommended fields.
- `robots_sitemap` — read robots.txt and discover the sitemap's URLs.
- `autocomplete_suggestions` — Google autocomplete for a phrase. Try:
  "autocomplete_suggestions for 'plumber near me'".
- `cluster_keywords` — group a keyword list into themes.
- `trend_index` — Google Trends interest and related queries for up to 5 terms.
- `pagespeed` — Lighthouse scores and Core Web Vitals for a URL. Works without a
  key but shares a small quota; add a free `PAGESPEED_API_KEY` for reliable use
  (see below).

Everything else (live Google Ads / Meta / GA4 / Search Console data) needs that
platform connected. Run `setup_check` any time to see what is connected.

## Connecting your accounts

There are two ways. Both write the same `.env` file; pick whichever is easier.

### Option A: connect from chat (easiest, no file editing)

Just talk to the assistant. Ask it to run `setup_instructions` for the steps,
then connect each platform by pasting your values into chat:

- Google Ads: say "connect google ads oauth" and paste your OAuth client id and
  secret (a browser opens to approve), then "connect google ads" with your
  developer token and 10-digit account id.
- Meta Ads: say "connect meta" and paste your access token.
- GA4 + Search Console: say "connect analytics" and paste the contents of your
  service-account JSON key.
- PageSpeed (optional): say "set pagespeed key" and paste a free API key.

Each `connect_*` tool writes the `.env` for you, applies it immediately (no
restart), and confirms by pinging the platform. Tokens are masked in the reply,
and `.env` is gitignored, so nothing is shown in full or committed.

### Option B: edit the .env file yourself

The `.env` file lives in the `marketing-mcp` folder you cloned. It is a hidden
file (the name starts with a dot), so create and open it from a terminal in that
folder rather than hunting for it in Finder.

1. Make it from the template:
   - macOS / Linux: `cp .env.example .env`
   - Windows: `copy .env.example .env`
2. Open it to edit:
   - macOS: `open -e .env` (opens in TextEdit)
   - Windows: `notepad .env`
3. Each line is `NAME=value`. Put your value right after the `=`, with no quotes
   and no spaces around it. Fill only the platforms you want; leave the rest
   blank. Example:
   ```
   META_ACCESS_TOKEN=EAAG...your token...
   ```
4. Save the file, then restart Claude (the server reads `.env` when it starts).

Run `python doctor.py` to see which platforms are configured, or `python doctor.py
--live` to also ping them.

## How to get each credential

Get a value from the platform, then either paste it in chat (Option A) or put it
on the matching `.env` line (Option B). You only need the platforms you plan to
use.

### Google Ads (keyword research, reporting, campaign management)

`GOOGLE_ADS_DEVELOPER_TOKEN`
1. Sign in at ads.google.com. The account must have a billing/payment method on
   file (you do not have to spend).
2. Click the tools icon (wrench) at the top, then Setup -> API Center.
3. Apply for a developer token; choose Basic access. Approval can take up to a day.

`GOOGLE_ADS_CLIENT_ID` and `GOOGLE_ADS_CLIENT_SECRET`
1. Go to console.cloud.google.com and create or pick a project.
2. APIs & Services -> Library -> search "Google Ads API" -> Enable.
3. APIs & Services -> Credentials -> Create Credentials -> OAuth client ID.
4. Application type: Desktop app -> Create. Copy the client ID and client secret.

`GOOGLE_ADS_REFRESH_TOKEN`
- Easiest: in chat say "connect google ads oauth" and paste the client id/secret;
  a browser opens, you approve, and it saves the token.
- Or in a terminal: `python oauth_setup.py <CLIENT_ID> <CLIENT_SECRET>`, approve
  in the browser, and copy the `GOOGLE_ADS_REFRESH_TOKEN=...` it prints.

`GOOGLE_ADS_CUSTOMER_ID`
- The 10-digit account number shown at the top of ads.google.com (format
  123-456-7890). Enter it without dashes: `1234567890`.

`GOOGLE_ADS_LOGIN_CUSTOMER_ID` (only if you use a manager account)
- The 10-digit id of your manager (MCC) account, digits only. If you have a single
  Ads account and no manager, leave this blank.

Note: without active ad spend on the account, keyword search volumes come back as
ranges (for example 1K-10K), not exact numbers. That is Google's limit.

### Meta Ads (reporting, management, ad library)

`META_ACCESS_TOKEN`
1. Go to developers.facebook.com -> My Apps -> Create App (type: Business).
2. Add the "Marketing API" product to the app.
3. Quick token (expires in 1-2 hours, fine for testing): Tools -> Graph API
   Explorer, pick your app, add the permission `ads_read` (and `ads_management`
   if you want the pause/activate tools), then Generate Access Token.
4. Long-lived token (does not expire): business.facebook.com -> Business Settings
   -> Users -> System Users -> create a system user -> Generate New Token, select
   your app and the `ads_read` permission.

### GA4 and Search Console (one service-account key serves both)

`GOOGLE_APPLICATION_CREDENTIALS` (a path to a JSON file)
1. console.cloud.google.com -> create or pick a project.
2. APIs & Services -> Library -> enable both "Google Analytics Data API" and
   "Google Search Console API".
3. APIs & Services -> Credentials -> Create Credentials -> Service account. Give
   it a name and click Done.
4. Click the new service account -> Keys -> Add Key -> Create new key -> JSON.
   A `.json` file downloads. Note the service-account email (it looks like
   `name@project-id.iam.gserviceaccount.com`).
5. In GA4: Admin -> Property Access Management -> add that email as a Viewer.
6. In Search Console: Settings -> Users and permissions -> add that email as a user
   (Restricted is enough for reading and URL inspection; choose Full only if you
   want `gsc_submit_sitemap` to be able to submit sitemaps).
7. Set `GOOGLE_APPLICATION_CREDENTIALS` to the full path of the downloaded JSON
   (in chat, "connect analytics" + paste the file's contents does this for you).

To use the tools you also need:
- GA4 property id: GA4 Admin -> Property Settings, a number like `123456789`. Pass
  it as `property_id`.
- Search Console site: the exact property string, e.g. `https://example.com/` or
  `sc-domain:example.com`. Pass it as `site_url`.

### PageSpeed (optional, for the pagespeed tool's quota)

`PAGESPEED_API_KEY`
1. console.cloud.google.com -> APIs & Services -> Library -> enable "PageSpeed
   Insights API".
2. APIs & Services -> Credentials -> Create Credentials -> API key. Copy it.

## Tools (53)

**SEO / site (no setup; PageSpeed is a free Google API)**
- `seo_score` — one 0-100 health score and letter grade, rolled up from the
  on-page audit, technical health, and readability, with the top fixes. Zero setup.
- `seo_audit` — fetch a URL and grade it: title, meta description, headings, word
  count, canonical, og/twitter tags, JSON-LD schema, images missing alt, link
  counts, and an issues list. Zero setup.
- `crawl_site` — crawl up to `max_pages` (sitemap-seeded or link-following,
  respecting robots.txt) and aggregate the most common issues site-wide.
- `check_links` — request every link on a page and report the broken (4xx/5xx)
  ones; scope = all / internal / external.
- `content_analysis` — Flesch reading ease, word/sentence counts, keyword density,
  heading outline, thin-content flag, and optional focus-keyword placement.
- `http_check` — redirect chain, HTTPS enforcement, security headers (HSTS, CSP,
  X-Content-Type-Options, X-Frame-Options), response time, server, mixed content.
- `validate_schema` — parse the page's JSON-LD, list each `@type`, flag invalid
  JSON, and report missing recommended properties for common schema types.
- `robots_sitemap` — parse robots.txt (Disallow rules + Sitemap directives) and
  walk the XML sitemap (handles a sitemap index) to count and sample page URLs.
- `pagespeed` — Lighthouse performance / SEO / accessibility scores plus Core Web
  Vitals (LCP, CLS, INP) for a URL. Set `PAGESPEED_API_KEY` (free) for quota.

**Search Console (organic search)**
- `gsc_top_queries` / `gsc_top_pages` — top organic queries and pages by clicks,
  impressions, CTR, and position over N days
- `gsc_search_analytics` — any dimensions (query, page, country, device, date)
- `gsc_list_sites` — properties the service account can read
- `gsc_inspect_url` — URL Inspection: is a page indexed, its coverage state, last
  crawl time, Google-chosen canonical, mobile usability, rich-results status
- `gsc_list_sitemaps` / `gsc_submit_sitemap` — list submitted sitemaps with their
  errors/warnings, and submit a new sitemap (submit needs full-user permission)

**Keyword research (bulk + locations)**
- `keyword_research` — one call: expand seed keywords and/or pull metrics for a
  keyword list, across many places at once, ranked by search volume and
  commercial intent, returned as decision-ready rows you act on in the same chat
  turn. Chunks under the API's 20-seed cap.
- `resolve_locations` — turn town/city/state names into Google Ads geo target ids
  with reach, so you target specific areas instead of the whole country
- `add_location_set` / `list_location_sets` — save a reusable named list of target
  areas; pass `location_set="<name>"` to the keyword tools
- `keyword_ideas` / `keyword_historical_metrics` also take `locations` / `location_set`
- `forecast_keywords` — projected impressions / clicks / cost at a max CPC bid
- `autocomplete_suggestions` — Google Suggest completions (no setup)
- `trend_index` — Google Trends interest + related queries
- `cluster_keywords` — group a keyword list into themes (no setup)

**Google Ads (reporting + management)**
- `list_ads_accounts` — accessible customer ids
- `ads_query` — run any GAQL query (the full reporting surface)
- `campaign_performance` — per-campaign metrics over N days
- `search_terms_report` — search terms + metrics
- `set_campaign_status` / `set_campaign_budget` — pause/enable, change budget

**Meta Ads (reporting + management)**
- `meta_list_ad_accounts`, `meta_list_campaigns`, `meta_list_adsets`, `meta_list_ads`
- `meta_insights` — spend / impressions / clicks / ctr / cpc / actions at any level
- `meta_ad_library` — search Meta's public Ad Library for competitor ads
- `meta_set_campaign_status` — pause / activate a campaign

**GA4 (analytics)**
- `ga4_run_report` — any dimensions x metrics over a date range
- `ga4_realtime` — realtime report
- `ga4_traffic_sources`, `ga4_top_pages` — convenience reports

**Clients (multi-account: granular + rollup)**
- `list_clients` / `add_client` — register clients in `clients.json`, each with its
  Google Ads, Meta, and GA4 account ids
- `clients_overview` — per-client KPIs across all platforms plus a rolled-up total
- every reporting tool also takes a `client` argument to target one client

**Setup**
- `setup_check` — which platforms are connected and the next step for the rest
- `setup_instructions` — the from-chat steps
- `connect_google_ads`, `connect_google_ads_oauth`, `connect_meta`,
  `connect_analytics`, `set_pagespeed_key` — connect from chat

The power tools (`ads_query` GAQL, `meta_insights`, `ga4_run_report`,
`gsc_search_analytics`) expose each platform's whole API surface, so the server
is not limited to the convenience tools.

## Multiple clients

Define each client once with `add_client` (or in `clients.json`, copy
`clients.example.json`) with its Google Ads customer id, Meta ad account id, and
GA4 property id. Then:

- granular: pass `client="acme"` to any reporting tool to scope it to that
  client's accounts.
- rollup: `clients_overview` returns a per-client KPI row for every client plus a
  single rolled-up total across all of them.

A platform a client has not connected shows an `*_error` note in the rollup
instead of a number. `clients.json` is gitignored, so client account ids never get
committed.

## Notes

- The Google Ads tools target the `google-ads` Python library v24+ (API v17+).
- Meta uses the Graph API v20.0 directly, so it needs only a token, no SDK.
- `.env`, `clients.json`, `location_sets.json`, and any service-account JSON are
  gitignored, so credentials never get committed.