SEO BANDWAGON

FOR DEVELOPERS & AI AGENTS

API & MCP SERVER

SEO Bandwagon exposes a remote MCP (Model Context Protocol) server and a small public REST API. Connect Claude or any MCP client to query your Google Search Console data and tracked keyword rankings programmatically.

MCP SERVER

  • Endpoint: https://seobandwagon.com/api/mcp
  • Transport: streamable HTTP
  • Auth: Authorization: Bearer sbw_<48 hex characters>

Example (Claude Code):

claude mcp add --transport http seobandwagon https://seobandwagon.com/api/mcp \
  --header "Authorization: Bearer sbw_<your key>"

API keys are issued per SEO Bandwagon account and shown once at creation. There is no self-serve key page yet — contact us to request one. All tools return data scoped to your account; unauthenticated requests receive 401.

AVAILABLE TOOLS

TOOLDESCRIPTION
gsc_connection_statusCheck the authenticated user's Google connection. Returns per-capability grant state (gsc.read, gsc.write, ga4.read, ads.read), the granted scopes, and whether the user needs to reconnect Google (the Connect button at seobandwagon.com/dashboard/search-console) to pick up newly added capabilities — sign-in itself grants identity only.
gsc_list_sitesList the Google Search Console properties the authenticated user has access to.
gsc_search_analyticsQuery Google Search Console search analytics for a property. Returns rows of clicks, impressions, CTR, position, and sum_position grouped by the requested dimensions, plus aggregation_type, pagination meta (has_more/next_offset, one API request per call, max 25,000 rows), and data-loss warnings — read the warnings before summing anything: query grouping under-counts, and byPage impressions must never be compared to byProperty. Use gsc_list_sites first for valid siteUrl values (e.g. 'sc-domain:example.com').
gsc_verify_data_availabilityGoogle's recommended preflight before any GSC reporting: which dates in the lookback window have data, which are still provisional (fresh, will change), and the latest date whose numbers are final. Build reports only up to latest_final_date; treat provisional_dates as an upsert window.
gsc_accurate_totalsGround-truth totals for a window: clicks, impressions, CTR, impression-weighted position, and sum_position from a pull with NO lossy dimensions. Use this as the denominator any time you sum query-grained rows — the sums will not match, and the gap is real data loss, not an error. Optional lossless breakdown dimensions: country, device, date.
gsc_coverage_reportMeasure what a query/page-grained analysis is blind to: pulls the detail rows and the matching accurate totals, and reports coverage_pct — the share of true impressions the chosen grain can see. State this number alongside any per-query conclusions. Coverage varies by window; measure it for the exact window you analyze.
gsc_compare_periodsCompare two date windows: aggregate deltas for clicks/impressions/CTR/weighted position, and per-key rows when dimensions are given. Rows have status 'both' (real deltas), 'new' (only in period 2), or 'lost' (only in period 1) — new/lost rows carry null metrics for the missing side and null changes; never read them as zeros. Percentage deltas vs a zero base are null.
gsc_top_queriesTop queries ranked by a chosen metric (clicks, impressions, ctr, position) over the full retrievable row set, then cut to limit — has_more means the ranked list was cut by your limit (raise limit or narrow the window; there is no startRow here). Optional per-query daily click trend for the top 20. Query-grained and therefore lossy: check warnings and gsc_coverage_report.
gsc_top_pagesTop pages ranked by a chosen metric over the full retrievable row set (byPage impression units — never compare to byProperty totals). Optional queryBreakdown: top 10 queries for each of the top 10 pages. Page rows are lossless; the per-page query lists are lossy and cut to 10 by Google.
gsc_query_page_pairsQuery→page attribution rows (the only way to get it) with byPage aggregation. The single most expensive request the GSC API offers — load scales with window length; keep windows short and avoid repeat pulls. Lossy at this grain: check warnings and gsc_coverage_report with entityType query_page.
gsc_search_appearanceRich-result (search appearance) performance: enumerates the property's appearance types, then optionally breaks each down by your dimensions via Google's documented two-step. Everything here is byPage-forced — do not compare these numbers to byProperty results.
gsc_inspect_urlInspect one URL's Google index status: verdict, coverage state, robots.txt/indexing state, last crawl, canonical pair, mobile usability, and detected rich results. Unknown enum values pass through verbatim — 'UNKNOWN' means the API omitted the field, never a fabricated verdict.
gsc_bulk_inspectInspect up to 10 URLs in one call (per-URL results plus a success/failed summary). For larger sets, call repeatedly — the cap keeps one call inside the serverless time budget; URL Inspection also has a daily quota, so inspect samples, not whole sitemaps.
gsc_list_sitemapsList submitted sitemaps for a property with pending/index-file flags, last download time, file errors/warnings, and per-content-type submitted/indexed counts as reported by the Sitemaps API.
gsc_sitemap_indexation_summarySubmitted vs indexed URL counts across sitemaps, as reported by the Sitemaps API — NOT the Index Coverage report (the public API does not expose it). Counts are only as fresh as each sitemap's last_downloaded; never-fetched sitemaps, stale fetches, and index-file double counting are all called out in warnings.
gsc_submit_sitemapSubmit (or resubmit) a sitemap to Google Search Console. Requires the Search Console manage grant (gsc.write) — reconnect via the Connect button at seobandwagon.com/dashboard/search-console if the connection predates it. Throws with the reason on failure; success is only reported when Google accepted the submission.
gsc_delete_sitemapRemove a sitemap from Google Search Console (does not delete the file from your server, only the submission). Requires gsc.write. Throws with the reason on failure.
gsc_analyze_opportunitiesScan for SEO opportunities: low-CTR queries worth better titles/snippets, striking-distance keywords (positions 4-10), and indexation-coverage gaps. Returns prioritized opportunities, quick wins, and an impact estimate — with warnings whenever an underlying pull was truncated or grain-lossy, so counts are labeled floors when they are floors.
gsc_content_gapsCluster queries where the site ranks poorly but gets impressions — candidate topics for new or expanded content, with per-cluster impressions and weighted position. Query×page grained (lossy; warnings included).
gsc_cannibalization_checkFind queries where multiple pages of the site compete: per-query page lists with click/impression splits and a consolidation recommendation. Query×page grained (lossy; warnings included).
rank_tracker_keywordsList the authenticated user's tracked keywords from the SEO Bandwagon rank tracker, with last known Google position, search volume, and GSC metrics. Optionally filter by domain.
rank_tracker_historyGet historical Google position checks (serp_history) for a domain the authenticated user tracks, optionally filtered to one keyword. Note: positions are only recorded when a rank check runs.
clients_listList clients (leads) visible to the authenticated user. Admins see the full roster; other users see only the client record linked to their account. Returns id, name, contact email, status, and notes — use the id with the client_audits_* tools.
clients_createCreate a client (lead) record. Admin-only. Provide a name; contact email, GSC site URL, notes, and status (e.g. 'lead', 'active') are optional. Returns the created client including its id.
client_audits_addAttach an audit report (markdown) to a client. Admin-only. Provide clientId (from clients_list/clients_create), the audited domain, a title, a kind tag (e.g. local-seo, gbp-listings, geo, summary), and the full markdown body. The report appears on the client detail page in the dashboard. Optionally pass pdfBase64 (plus pdfFilename) to attach the branded PDF — the prospect share page then renders the PDF instead of the markdown, which matters for reports with wide tables or diagrams.
client_audits_listList audit reports attached to a client (id, domain, title, kind, created date; bodies omitted unless includeContent is true). Admins can read any client; other users only their own.
client_share_linkGet the share URL for a client's gated audit page (seobandwagon.com/audit/<slug>, e.g. /audit/moli-windows). The page shows a teaser and requires Google sign-in; the first account to sign in claims the client record (sets its linked user + contact email). Admin-only. Generates the slug (and a legacy token) on first call; pass rotate=true to rotate the legacy token — the slug URL is unaffected.
ga4_list_propertiesList the GA4 accounts and properties this Google account can access, with numeric property ids. Property ids ('123456789') are what every other ga4_* tool takes — never the G-XXXXXXX measurement id.
ga4_property_detailsOne property's settings (timezone, currency), its data streams (with G-XXXXXXX measurement ids and site URLs), and its configured key events — the metric behind keyEvents in reports.
ga4_run_reportRun a GA4 Data API report: any dimensions/metrics (discover them with ga4_metadata), optional FilterExpression filters and orderBys, limit/offset paging. Responses ALWAYS disclose data-quality caveats as warnings — sampling (with the sampled %), '(other)'-row collapse, privacy thresholding, truncation — plus API-computed totals and property quota state. Read the warnings before trusting differences between numbers.
ga4_realtime_reportActive users right now, by screen/page and other realtime dimensions. Totals come from the API aggregation — summing dimension rows double-counts users appearing in multiple rows.
ga4_landing_pagesLanding-page performance bundle: sessions, users, new users, bounce rate, engagement rate, session duration, and key events per landingPage — the GA4 counterpart of gsc_top_pages, with loss-disclosure warnings.
ga4_organic_search_performanceGoogle-organic landing-page performance: sessions/users/keyEvents per landingPage filtered to sessionSource=google AND sessionMedium=organic — the GA4 slice whose traffic scope corresponds to Search Console, and the input to GSC↔GA4 cross-verification.
ga4_metadataDiscover the dimensions and metrics (including custom definitions) a property supports, or — with checkDimensions/checkMetrics — pre-flight a combination for compatibility before running an expensive report.
gsc_ga4_page_joinCross-verify Search Console against GA4 per page: GSC clicks/impressions/position joined to GA4 google-organic sessions/users/keyEvents on normalized landing-page paths, with unjoinable rows in gsc_only/ga4_only buckets (never silently dropped), BOTH sources' loss warnings labeled by source, and scope_notes explaining why the two never match exactly (clicks≠sessions, timezone boundaries, anonymized queries vs untagged visitors). Use it to validate that sampled/thresholded GA4 numbers are consistent with GSC ground truth.

PUBLIC REST API

The captures API stores and retrieves on-page SEO analyses from the SEO Bandwagon Chrome extension. No authentication required.

  • POST /api/v1/captures — ingest a full SEO analysis payload. Same-URL captures are deduped within one hour (409).
  • GET /api/v1/captures?url=… — fetch up to 50 captures for a URL, matching across protocol, www, and trailing-slash variants.

MACHINE-READABLE DISCOVERY

Agents can discover these services automatically: