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 local-SEO checks, prospecting, email and copy checks, site hygiene, AI-assistant visibility, and a multi-client rollup. Fourteen workflows, written as skill chains, run whole jobs end to end. 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.

License

Proprietary and confidential. Copyright (c) 2026 The Wayfinder Trust. See LICENSE. Licensed only under a separate written agreement. There is no public distribution, and possession of a copy conveys no rights.

Related MCP server: Google MCP Server

Install

Supplied to licensees as a source archive or through a private repository grant. Python 3.10+ required.

macOS / Linux (on macOS brew install python@3.11):

cd marketing-mcp
bash install.sh

Windows (Python 3.10+ from python.org):

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.

• growth_signals: the growth stack a site runs today: ad pixels, affiliate and analytics tools, social profiles, and what its robots.txt tells each AI crawler. Try: "growth_signals for https://example.com".

• growth_teardown: name a company's domain, get a dated timeline of its growth moves read from archived copies of its homepage. Try: "growth_teardown for example.com".

• 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).

• money_page_check, competitor_page_gap, missing_pages, crawl_depth, internal_link_plan, image_check: the weekly local-SEO checks (see Tools).

• find_businesses, prospect_finding, call_sheet: a prospect list from open map data and a call sheet whose openers rest on real findings.

• email_auth_check, verify_email, copy_check: check a sending domain, an address, or a draft before it goes out.

• sitemap_hygiene, duplicate_audit, assistants_index, schema_build: site hygiene and the llms.txt index for AI assistants.

AI visibility needs no key either: in Claude Code the buyer questions are answered by fresh subagents that have never seen your chat. Everything else (live Google Ads / Meta / GA4 / Search Console data) needs that platform connected. Run setup_check any time to see what is connected.

Workflows

The workflows live in workflows/ in skill-chain format: each step is a flow folder (workflows/flows/<flow>/skill.md with phases and quality gates, plus manifest.json), and each workflow is a chain (workflows/chains/<name>.chain.json). A step either runs on this server (it calls the tools its manifest lists) or is done by Claude in the chat (writing, judging, choosing). No step is handed to a person.

Run one from chat with its prompt (each workflow is also an MCP prompt of the same name), or with the tools:

• list_workflows: every workflow with its inputs and steps

• run_workflow: start one; tool steps run at once, and the run pauses at a step Claude does, returning that step's instructions and inputs

• continue_workflow: send that step's outputs and keep going; with no outputs it retries a step that was blocked on setup

To change a workflow, edit the contract in workflows/build_workflows.py, run it to regenerate the files, and run python test_workflows.py, which checks every chain against the skill-chain rules and against the tools this server registers.

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.

Anthropic (optional, for AI visibility outside Claude Code)

Not needed in Claude Code: there the ai-visibility-baseline workflow has fresh subagents answer the buyer questions, each starting without your chat or the project's instructions. Where subagents are not available (Claude Desktop), a key lets ask_assistant do the same through the API.

ANTHROPIC_API_KEY

1. platform.claude.com -> API keys -> Create key. Copy it.

2. In chat: "set_anthropic_key with ". Each buyer question then goes to Claude as a fresh conversation with web search on and no history. Model: claude-opus-5-5 unless MARKETING_MCP_ASK_MODEL names another.

Tools (86)

Local SEO (no setup; the weekly checks of a local-business SEO practice)

• money_page_check: is the target keyword in the page's visible text, title, H1, URL slug, first 100 words and meta description; a keyword missing from the visible text is flagged first.

• competitor_page_gap: your page against up to three competitor pages: title, meta, H1, H2s, word count, keyword placement, schema types and trust facts; flags over-use of the keyword and lists what every competitor says that you do not.

• missing_pages: page topics competitors have and your site lacks, ranked by how many competitors have each.

• crawl_depth: clicks from the homepage to every page; money pages deeper than two clicks and sitemap pages no link reaches.

• internal_link_plan: for a new post: 3 to 5 posts and 1 money page to link to, and 3 older posts to link from, each with its anchor sentence.

• paid_vs_organic: split keyword rows into SEO first, ads now with SEO long-term, ads for speed, or ads only, by click cost and difficulty; difficulty is never invented.

• image_check: file names, alt text, format, lazy loading, dimensions, and images per 250 words.

Prospecting (no setup)

• find_businesses: independent businesses in an area by category from OpenStreetMap, chains dropped, with website and phone where listed.

• prospect_finding: one graded finding (A, B, or C for clean) per site with the evidence it rests on; never invented on a clean site.

• call_sheet: prospects into a call sheet with a two-sentence opener built only from the finding and your offer, plus a voice-agent list and CSV.

• agency_score: score an agency as a reseller partner, with what to ask on the call.

Email and copy (no setup; nothing is ever sent)

• email_auth_check: SPF, DKIM, DMARC and MX for a sending domain, with fixes.

• verify_email: syntax, mail server, role, free and disposable flags, and an optional SMTP probe that never sends.

• dmarc_report: read a DMARC aggregate report into sources, results and pass rate.

• classify_replies: sort replies into dead address, policy block, out of office, address change, unsubscribe, other auto-reply, or human reply.

• send_window: each recipient's local mid-morning send time, batched.

• copy_check: AI tells, hype words, hedges, long sentences, spelling locale, and numbers without a source.

Site hygiene (no setup)

• duplicate_audit: exact and near duplicates, shared titles and H1s, orphans, broken internal links, redirects owed.

• sitemap_hygiene: robots.txt and sitemap checks, lastmod, noindex and canonical conflicts, mixed hosts, and the AI crawler rules.

• schema_build: JSON-LD for a local business, its services, FAQs and founder.

• assistants_index: an llms.txt index for AI assistants from a site's own pages.

• cover_image: a title card PNG checked against the area social previews keep.

• strip_metadata: remove author, template and provenance metadata from Office files, PNG and JPEG before publishing.

AI visibility

• visibility_questions: a fixed set of buyer questions for a business.

• ask_assistant: ask Claude each question in a fresh API session with web search on; optional, for clients without subagents; needs ANTHROPIC_API_KEY.

• visibility_record: whether each answer named the business, its position, and the competitors named; kept in a local file.

• visibility_report: share of answer over time and the questions never won.

Workflows

• list_workflows, run_workflow, continue_workflow: see Workflows above.

Growth teardown (no setup; reads the site and the Internet Archive from your machine)

• growth_signals: read a site's homepage, tag-manager container, robots.txt and llms.txt, and report by lane: ads and tracking (Google Ads, Meta, TikTok, LinkedIn, Reddit, Microsoft, X, Pinterest pixels and attribution tools), affiliates and referral programs, analytics, lifecycle and CRM tools, experimentation, social profiles, site sections grouped by growth play, AI-search readiness (llms.txt, per-crawler robots rules, answer schema), the numbers the site states about itself, and the sitemap by section. A site behind a bot wall is read from its newest archived copy, and source says so.

• growth_teardown: sample archived copies of a domain's homepage across years (up to max_snapshots), run the same reading on each, and return a timeline: each signal with the snapshot it was first seen in and the last snapshot it was absent from, plus homepage title changes, the first archive capture of llms.txt and of each named section's own page (page_first_archived, an exact date), and new URLs per quarter when the archive index returns the site's URL list. Every first-seen date is a bracket between two snapshots. Funding, revenue and ad spend are listed under not_covered, never estimated.

• growth-blueprint (workflow): chains growth_teardown, growth_signals, trend_index, meta_ad_library and a news search for funding dates into one timeline by lane, each row tied to its source.

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, set_anthropic_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. So are the local stores the newer tools keep: ai_visibility.json, workflow_runs.json, and the covers/ folder. Set MARKETING_MCP_DATA_DIR to keep the stores elsewhere.

• Tests: test_growth.py, test_seo_rules.py, test_prospecting.py, test_email_checks.py, test_copy_check.py, test_site_hygiene.py, test_ai_visibility.py, test_workflows.py; each runs offline and ends with "all checks passed".