Marketing Data Hub

Your marketing data, on your machine, free. An open-source Windsor.ai alternative: pulls Google Analytics 4, Search Console (plus Google Ads, Meta Ads, YouTube) into one local database — queryable via a REST API, scheduled CSV exports, and by AI assistants like Claude (MCP). No hosted service, no subscription, your tokens never leave your computer.

Quick start

Windows: download MarketingDataHub-Setup.exe (or see all versions on the releases page) and run it — the setup page opens in your browser.

Anywhere with Python 3.11+:

python3 -m pip install marketing-data-hub
python3 -m hub.cli setup

(Use python3 -m pip/python3 -m hub.cli rather than bare pip/hub — on Mac especially, pip on your PATH can point at a different Python than python3, so a bare pip install can succeed while hub still isn't found. python3 -m ... always installs into and runs from the same interpreter.)

(Developers: git clone https://github.com/Bhargava-R-dev/marketing-data-hub and pip install -e ".[dev]" instead.)

The setup page walks you through: sign in to Google → tick the GA4 properties / Search Console sites you want → watch the first sync load, account by account → connect Claude (one click) → done, with the daily 6am sync scheduled for you and a Marketing Data Hub icon on your Desktop / Start Menu. That icon is the everyday entry point: add or remove accounts, sync now, open the dashboard — no command window (hub shortcut recreates it).

Your hub lives in %LOCALAPPDATA%\MarketingDataHub (Windows) or ~/.marketing-data-hub (Mac/Linux); nothing to configure. A config.yaml in the current folder takes precedence, so existing checkouts keep working. Prefer your own Google Cloud project over the bundled sign-in? Drop your google_client.json in that folder's secrets/ — the setup page shows which one is in use (SETUP.md step 2).

Never used a terminal? → GUIDE.md is a complete, plain-English walkthrough from installing Python through asking your first question — written for non-technical teammates, and made to be shared.

Then ask Claude things like "How did organic traffic do in June vs May?" or "Top non-branded search queries this month?" — or automate a daily 6am sync (SETUP.md, step 8).

Related MCP server: Google Analytics MCP Server

Reports (analysis shapes)

Each source syncs several named reports — different dimensional shapes of the same data, stored side by side and never mixed (mixing granularities would double-count):

GA4 breakdown reports exclude GA4's unattributable (other) bucket, so they sum to slightly under the topline (on very large properties, well under for high-cardinality dims like landing pages) — use core for exact totals, breakdowns for composition/ranking. Same idea as GSC query anonymisation.

Pass report=<name> to the API/MCP query_metrics; default is core. MCP query_metrics also supports compare= (prev_period / prev_day / prev_week / prev_month / prev_year — returns value, previous, and %-change per metric for any date range) and filters= (exact match on any dimension incl. report extras, e.g. {"event": "form_submit"} or {"device": "MOBILE"}). Rates are computed, not stored: engagement rate = engaged_sessions/sessions, ctr = clicks/impressions, avg engagement time = engagement_seconds/pageviews. GSC breakdown reports undercount totals slightly (Google anonymises rare queries) — use core for toplines. True user-level cohorts need the GA4 BigQuery export; visitors + the live tools cover cohort-lite analysis.

For anything the synced reports don't cover, the MCP tools query_ga4_live and query_gsc_live pass arbitrary dimension/metric combinations straight to the APIs on demand.

Setup

New here / installing on another machine? Follow SETUP.md — a step-by-step guide including the Google Cloud OAuth setup. Quick version:

1. python -m pip install -e ".[dev]"

2. Copy config.yaml.example → config.yaml; fill in your GA4 property_id and Search Console site_url. Have multiple GA4 properties or Search Console sites under the same Google login? Use property_ids: [...] / site_urls: [...] instead — all of them sync, and every row is tagged with its own account_id so they stay distinguishable downstream.

3. Copy .env.example → .env; set a random HUB_API_KEY.

4. Google Cloud Console → create a project → enable Google Analytics Data API, Google Analytics Admin API, Search Console API, YouTube Analytics API → create an OAuth client (Desktop app) → download JSON to secrets/google_client.json. (See SETUP.md for the OAuth consent-screen steps and the 7-day token-expiry gotcha.)

5. hub doctor — first run opens a browser to authorize; then all checks go green.

6. hub accounts --add — pick which GA4 properties / GSC sites to sync from everything your Google login can see.

Daily use

Query API

GET /connectors/all/data?fields=date,source,clicks,spend&date_preset=last_30d
X-API-Key: <HUB_API_KEY>

format=csv for CSV, report=<name> for a breakdown report. /connectors lists sources; /connectors/{source}/reports lists report shapes; /connectors/{source}/fields?report=<name> lists fields.

Claude MCP

claude mcp add marketing-hub -- python -m hub.cli mcp --config <absolute-path>/config.yaml Then ask Claude: "How did my campaigns do last week?"

Note: use an absolute path for --config; the MCP process may be launched from a different working directory.

trigger_sync starts the sync in the background and returns immediately (output goes to logs/mcp_sync.log); poll sync_status to see when it finishes. While a sync holds the write lock, query tools return a readable "database is busy" error instead of hanging.

Activating the ad connectors

• Google Ads: apply for a developer token (API Center), then uncomment google_ads in config.yaml and fill options.

• Meta Ads: create a Meta app, generate a long-lived token with ads_read, uncomment meta_ads and fill options.

Known limitations

• DuckDB allows one writer: run hub mcp OR hub serve, not both at once (trigger_sync from MCP spawns the CLI, which needs the write lock free). While any sync runs, MCP query tools report "database is busy" until it finishes (~3 min for sync all).

• Extras fields (e.g. position, ctr, views) are returned as strings by the query API — cast numerically as needed.