flin-gmp-mcp
Use Google Marketing Platform data in Claude Desktop through authenticated, mostly read-only tools, with limited DV360 report creation/run functionality.
Check local setup, health, version/update status, and auth readiness; sign in via browser with optional named accounts.
GMP Admin: list/get organizations and list linked Analytics accounts (no GA4 reporting).
DV360: discover partners, advertisers, campaigns, insertion orders, line items, and creatives; create/run saved report queries, list queries/runs, check report status, and read bounded CSV report rows.
CM360: discover profiles; list advertisers, campaigns, creatives, saved reports, and report files; get creative/report-file metadata and existing download URLs.
SA360: list customers, discover manager child accounts, run read-only SELECT queries, search fields, list custom columns, and fetch campaign performance.
Supports pagination and multiple Google accounts; does not expose arbitrary HTTP or mutate campaigns, budgets, targeting, creatives, or account links.
Provides read-only access to Google Marketing Platform products, including GMP Admin organizations and linked Analytics accounts, Display & Video 360 advertisers/campaigns/line items/creatives and reporting metadata, Campaign Manager 360 profiles/campaigns/saved reports/file URLs, and Search Ads 360 customer discovery, campaign performance, custom SELECT queries, and field discovery.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flin-gmp-mcp List my DV360 partners and their active campaigns"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
flin Google Marketing Platform MCP
Use Google Marketing Platform data in Claude Desktop: DV360 campaigns and reports, CM360 metadata/report links, and SA360 performance. DV360 report creation and runs save resources at Google; campaigns, budgets and targeting are not changed.
Start in Claude Desktop on a Mac
For Apple Silicon (M1 or newer), use a current Claude Desktop supporting uv-based extensions. The same package also supports Intel Macs. No developer tools or local Git checkout are needed; the first launch needs internet access.
Download the standard Claude Desktop package. Versioned downloads and checksums remain available.
Install the
.mcpbthrough Claude Desktop's extension settings.Enter the settings supplied by your administrator or password manager: Google OAuth Client ID and Google OAuth Client Secret (Desktop app client). Under Enabled products, select the products you use:
admin,dv360,cm360,sa360. Keep Automatic server updates enabled. The administrator must enable the corresponding Google APIs; your Google account needs access to those products.Sign in: ask Claude to run
connection_status, thenauthenticate, and complete Google consent in the browser. Data/status tools never open a browser.Test access: run one matching discovery tool below. This is a small API read, not report creation. An empty successful response is possible; check access to the intended product/account separately.
connection_statusitself only checks local setup and always reportslive_access: not_checked.
Enabled product | Concrete access test |
GMP Admin |
|
DV360 |
|
CM360 |
|
SA360 |
|
The extension version identifies the installed starter. connection_status.server_version
identifies the server actually running. Compatible stable server updates load at
restart without interrupting a session or replacing saved settings. Cached/bundled
fallbacks are visible with the new starter; see updates and compatibility.
An older starter can require one new package import for those diagnostics or a
changed UI; the server update alone does not replace the starter. A 0.1.4 install
needs Automatic server updates enabled once.
Privacy · Security · Help and removal
Related MCP server: ga4-mcp
Supported products
Product | Tools and data | API |
GMP Admin | Organizations and linked Analytics accounts | v1alpha |
Display & Video 360 | Partners, advertisers, campaigns, insertion orders, line items, creatives | v4 |
DV360 reporting | Create report queries, start runs, read status and CSV values | Bid Manager v2 |
Campaign Manager 360 | User profiles, advertisers, campaigns, creatives with sizes/assets, saved reports and existing file metadata/URLs | v5 |
Search Ads 360 | Customer discovery, manager hierarchy, campaign performance, custom SELECT queries and field discovery | Reporting v0 |
GA4 reporting belongs in the separate flin-ga4-mcp. Google Ads, Search Console
and Google Tag Manager are outside this package's scope. GMP account links are
Analytics account links, not a universal cross-product account directory.
No campaign mutations, account linking or arbitrary HTTP requests are exposed. DV360 reports can be created and run, and completed CSV results can be read. CM360 reports still return existing metadata and URLs only. SA360 returns performance rows directly. DV360 uses v4; v5 was still labelled beta in Google's documentation when this implementation was verified on 2026-10-30.
Developer installation from this repository
Requires Python 3.10+ and uv.
uv sync --locked --extra devCreate a Google Cloud project and enable the APIs you will use:
Google Marketing Platform Admin API (
marketingplatformadmin.googleapis.com)Display & Video 360 API (
displayvideo.googleapis.com)DoubleClick Bid Manager API (
doubleclickbidmanager.googleapis.com)Campaign Manager 360 API (
dfareporting.googleapis.com)Search Ads 360 Reporting API (
searchads360.googleapis.com)
Configure the Google OAuth consent screen, add your account as a test user if using Testing mode, and create an OAuth client of type Desktop app. The Google account must already have access to the relevant products. OAuth consent alone does not grant product access. CM360 also requires an API-enabled user profile.
Add this configuration to a stdio MCP client such as Claude Desktop, replacing the checkout path and OAuth values:
{
"mcpServers": {
"flin-gmp-mcp": {
"command": "uv",
"args": [
"run", "--directory", "/absolute/path/to/flin-gmp-mcp",
"--locked", "flin-gmp-mcp"
],
"env": {
"GOOGLE_CLIENT_ID": "your-desktop-client-id",
"GOOGLE_CLIENT_SECRET": "your-desktop-client-secret"
}
}
}
}Restart your MCP client. Then ask it to:
Run
health_check.Run
authenticate, finish Google sign-in in the browser, and grant the requested permissions.Discover IDs using
list_organizations,list_dv360_partners,list_cm360_profiles, orlist_sa360_customers.Use those IDs in the corresponding data tools.
authenticate waits up to 180 seconds; configure a longer tool timeout in your
client if necessary. It requires a browser on the computer running the server.
Data tools never launch a browser; they return oauth_required when sign-in is
needed. Access tokens refresh automatically. Use authenticate(force=true) to
replace a stale login or switch the selected account. No secrets are returned.
Install from PyPI
uvx flin-gmp-mcp@latestIn an MCP client, use command: "uvx" with args: ["flin-gmp-mcp@latest"]
and the same Google environment variables shown above.
Configuration
Variable | Required | Meaning |
| Yes | Desktop OAuth client ID, same convention as flin Search Console |
| Yes | Desktop OAuth client secret |
| No | Comma-separated subset of |
| No | Absolute path to a dedicated private token directory |
| No | Loopback port; |
| No | Optional quota project ID, sent as |
Environment variables are read from the process. .env.example is a reference;
.env files are not automatically loaded.
Only enabled products' scopes are requested. Disabled products return a
configuration error. After adding a product, run authenticate again to grant its
scopes. A token created by a different OAuth client is rejected.
Multiple accounts and token storage
Pass account="work" to authenticate and subsequent calls to use a separate
Google login. Aliases use lower-case letters, digits, _ and -, start with a
letter or digit, and have at most 64 characters. Omit account for the default
login; the name default is reserved.
Default directories:
macOS:
~/Library/Application Support/flin-gmp-mcp/Linux:
$XDG_CONFIG_HOME/flin-gmp-mcp/or~/.config/flin-gmp-mcp/Windows:
%APPDATA%\flin-gmp-mcp\
The default token is default.json; named accounts use <account>.json. Writes
are atomic and files use mode 0600 on POSIX. New directories use 0700. Existing
directories must be owned by the user with mode 0700; token files must be
owned by that user with mode 0600. Unsafe storage is rejected on reads and writes.
Symlinked directories/files, hard-linked files and oversized token files are rejected. Never commit
these files. To disconnect locally, stop the server and delete the corresponding
token file; revoke the app in your Google account to invalidate its access.
OAuth scopes and campaign protection
Product | Scope suffixes under |
GMP Admin |
|
DV360 |
|
CM360 |
|
SA360 |
|
Google's 360 APIs require scopes that can also permit writes. The MCP enforces a fixed endpoint/method allowlist: GET requests, SA360 reporting/field-search POSTs, and Bid Manager POSTs only to create queries and run reports. Campaigns, budgets, bids, targeting, creatives and account links cannot be changed. Report creation and execution are marked as non-read-only, non-idempotent tools; they create saved Google report resources. No delete or update endpoints are exposed.
Results and pagination
Data tools return { "ok": true, "service": "...", "account": "...", "data": {...} }.
data preserves Google's native response, including field masks, currencies,
report statuses and nextPageToken. The list key varies by API (organizations,
advertisers, items, results, etc.). Empty responses are valid.
Each list/search call returns one page. If data.nextPageToken is present,
pass it as page_token with all other arguments unchanged. Do not report the
first page as the full account total. Limits: DV360 200, Bid Manager 100,
GMP Admin 1000, CM360 1000 (local cap), SA360 data search 10000. Responses over
10 MiB are rejected; reduce the page size or selected fields. Requests have a
10-second connection and 60-second read timeout, with no automatic quota retries.
Google requests and browser sign-in run in worker threads so a slow call does not
block the MCP event loop or unrelated tool calls. Cancelling a tool does not stop
an already running HTTP request; its transport timeout still applies.
SA360 IDs are bare digits without hyphens. login_customer_id selects the manager
through which access is granted. list_sa360_customers lists directly accessible
customers only; get_sa360_customer_clients discovers manager children.
get_sa360_campaign_performance uses inclusive account-timezone dates and returns
costMicros in millionths of customer.currencyCode.
Development
uv sync --locked --extra dev
uv run ruff check .
uv run pytest
uv buildTests use mocked Google responses, including transport/authentication failures, request contracts and a real local MCP stdio handshake. No Google credentials are required. Live product access must be verified separately with your account.
References
Implementation conventions follow flin Search Console and flin Google Ads.
Verified against Google's REST references and live discovery documents:
MIT © flin GmbH.
Automatic desktop server updates
The standard extension enables automatic PyPI updates at restart. The current starter accepts stable 0.1.x releases at or above its bundled version. The boundary covers the existing Python 3.12/stdio entry point, OAuth configuration, token format and tool interfaces. Future 0.2/1.x interfaces are not presumed compatible. Every release verifies the current and original 0.1.4 bundles against the new PyPI server, including synthetic saved settings and tokens across two starts.
connection_status and health_check expose server_version; health_check.version
remains supported. New starters also report extension_version, runtime_source,
update_status and fallback_active. Old starters report unknown provenance; no
fallback claim is inferred from a version number. See update details.
DV360 performance without a manually prepared report
Discover the advertiser ID, then reuse a matching
list_dv360_report_queriesresult or callcreate_dv360_report_query(title, advertiser_id).Call
run_dv360_report(query_id). It starts asynchronously and returns the report key.Check
get_dv360_report(query_id, report_id)with pauses untilDONEorFAILED.Read
read_dv360_report_rows(query_id, report_id)and follownext_row_offset.
New definitions default to STANDARD CSV reports for yesterday in the advertiser's
timezone, with impressions and clicks by date and advertiser. Custom metrics and
dimensions use Bid Manager METRIC_* and FILTER_* names; Google checks their
compatibility. Supply both start_date and end_date for an explicit date range.
Creation saves a query but does not run it. There is no automatic daily schedule,
email notification or sharing on newly created queries. Running an existing query
honors its existing notification settings. Reuse saved definitions for later days.
CSV downloads are capped at 10 MiB and 1000 records per returned page. Values stay strings to preserve precision; output includes headers, totals and footer records. Use column labels for units and currencies and never add totals to detail rows. Downloads only use HTTPS Google Storage URLs obtained from authenticated report metadata, without forwarding Google OAuth credentials or following redirects. After an uncertain create/run outcome, list queries/runs before retrying to avoid duplicates. A completed report may still reflect Google's data processing delay.
DV360 report creation and CSV reading require server version 0.1.3 or newer.
Available Tools
33 toolsauthenticateA
Sign in via the local browser and store credentials privately; never returns tokens.
Uses a Desktop OAuth client and a loopback callback (180-second timeout). Choose a lower-case account alias such as work for a separate login. force=true replaces the selected account's saved sign-in only after a successful new authorization. Requests permissions for GOOGLE_GMP_SERVICES; some Google scopes also allow writes, but this server only exposes reads and DV360 report creation/runs. Requires a browser on the server host.
Inputs: force, account. Returns: object
connection_statusARead-onlyIdempotent
Check local setup, version and update source without network, refresh or browser.
A stored token is not proof of current Google access: auth_status stays unknown until an actual authentication/access check. This local tool always reports live_access=not_checked and returns no credentials or customer data.
Inputs: account. Returns: object
create_dv360_report_queryA
Create a saved STANDARD CSV report definition; never changes campaigns.
Defaults to yesterday in the advertiser timezone, impressions/clicks by date and advertiser. Supply Bid Manager METRIC_* and FILTER_* identifiers for other fields; Google validates compatible combinations. Custom dates require both YYYY-MM-DD dates. No email, sharing or automatic schedule is enabled. This creates a persistent query, not a report run: use run_dv360_report next. Reuse matching queries to avoid duplicates. After a timeout, list queries before retrying: creation may already have succeeded.
Inputs: title (required), advertiser_id (required), account, metrics, +3 more. Returns: object
get_cm360_creativeARead-onlyIdempotent
Get full CM360 creative metadata including sizes, assets and available serving URLs.
Use IDs from list_cm360_creatives. For HTML5, inspect creativeAssets with role BACKUP_IMAGE. No image download/preview URL is documented for those assets; progressiveServingUrl and streamingServingUrl are documented for video only. Click-through/tracking URLs are not image URLs. Never construct CDN URLs from asset names or execute returned htmlCode. Missing assets/URLs remain missing.
Inputs: profile_id (required), creative_id (required), account. Returns: object
get_cm360_report_fileBRead-onlyIdempotent
Get existing CM360 report file metadata and download URLs; does not download CSV content.
Inputs: file_id (required), report_id (required), profile_id (required), account. Returns: object
get_dv360_advertiserCRead-onlyIdempotent
Read one DV360 advertiser's settings.
Inputs: advertiser_id (required), account. Returns: object
get_dv360_reportBRead-onlyIdempotent
Get an existing DV360 report's status and metadata, including its URL when available.
Inputs: query_id (required), report_id (required), account. Returns: object
get_organizationBRead-onlyIdempotent
Get a GMP organization by ID or organizations/{id} from list_organizations.
Inputs: organization (required), account. Returns: object
get_sa360_campaign_performanceARead-onlyIdempotent
Campaign impressions, clicks, cost_micros, conversions and conversion value.
Dates must be YYYY-MM-DD, inclusive, in the customer account's timezone. Currency is customer.currency_code; divide costMicros by 1,000,000 for currency units. Query an advertiser/client account, not an aggregate manager, for performance metrics.
Inputs: end_date (required), start_date (required), customer_id (required), account, +4 more. Returns: object
get_sa360_customer_clientsCRead-onlyIdempotent
Discover client accounts beneath an SA360 manager, including hierarchy levels.
Inputs: customer_id (required), account, page_size, page_token, +1 more. Returns: object
health_checkARead-onlyIdempotent
Check local configuration and token status. No Google request or browser launch.
'ready' or 'refreshable' describes credentials only, not verified product permissions.
Inputs: account. Returns: object
list_analytics_account_linksBRead-onlyIdempotent
List Analytics accounts linked to a GMP organization; no GA4 performance data.
Inputs: organization (required), account, page_size, page_token. Returns: object
list_cm360_advertisersBRead-onlyIdempotent
List CM360 advertisers for a user profile; optional native name/ID search with * wildcards.
Inputs: profile_id (required), search, account, page_size, +1 more. Returns: object
list_cm360_campaignsCRead-onlyIdempotent
List CM360 campaigns. Omit archived for both active and archived campaigns.
Inputs: profile_id (required), search, account, archived, +3 more. Returns: object
list_cm360_creativesARead-onlyIdempotent
List CM360 creatives with names, types, sizes and creativeAssets (one page, max 1000).
Filter by advertiser/campaign, IDs, native creative types or name/ID search (* allowed). Omit active/archived to include both states. Preserve filters for nextPageToken. HTML5 backup assets have role BACKUP_IMAGE; assetIdentifier.name is a filename, not a downloadable URL. This returns metadata, not image bytes or rendered HTML5.
Inputs: profile_id (required), types, active, search, +7 more. Returns: object
list_cm360_profilesBRead-onlyIdempotent
Discover accessible CM360 user profiles. Choose profileId for subsequent CM360 tools.
Inputs: account. Returns: object
list_cm360_report_filesBRead-onlyIdempotent
List existing CM360 report files and their status; no new report is generated.
Inputs: report_id (required), profile_id (required), account, page_size, +1 more. Returns: object
list_cm360_reportsBRead-onlyIdempotent
List saved CM360 report definitions visible to this profile. Does not execute reports.
Inputs: profile_id (required), scope, account, page_size, +1 more. Returns: object
list_dv360_advertisersBRead-onlyIdempotent
List advertisers for a discovered partner ID (required by DV360 v4; max 200).
Inputs: partner_id (required), filter, account, page_size, +1 more. Returns: object
list_dv360_campaignsARead-onlyIdempotent
List DV360 campaigns settings (max 200). These are not performance metrics.
Optional native DV360 filter; use the same filter when requesting the next page.
Inputs: advertiser_id (required), filter, account, page_size, +1 more. Returns: object
list_dv360_creativesBRead-onlyIdempotent
List DV360 creatives settings (max 200). These are not performance metrics.
Optional native DV360 filter; use the same filter when requesting the next page.
Inputs: advertiser_id (required), filter, account, page_size, +1 more. Returns: object
list_dv360_insertion_ordersBRead-onlyIdempotent
List DV360 insertion orders settings (max 200). These are not performance metrics.
Optional native DV360 filter; use the same filter when requesting the next page.
Inputs: advertiser_id (required), filter, account, page_size, +1 more. Returns: object
list_dv360_line_itemsBRead-onlyIdempotent
List DV360 line items settings (max 200). These are not performance metrics.
Optional native DV360 filter; use the same filter when requesting the next page.
Inputs: advertiser_id (required), filter, account, page_size, +1 more. Returns: object
list_dv360_partnersBRead-onlyIdempotent
Discover DV360 partners (max 200 per page). Optional native DV360 filter.
Inputs: filter, account, page_size, page_token. Returns: object
list_dv360_report_queriesBRead-onlyIdempotent
List existing DV360 report definitions via Bid Manager v2 (max 100). Reuse matching queries.
Inputs: account, page_size, page_token. Returns: object
list_dv360_reportsARead-onlyIdempotent
List existing runs of a DV360 report query, including available report metadata/URLs.
Does not run reports or fetch report CSVs. Use a query ID from list_dv360_report_queries.
Inputs: query_id (required), account, page_size, page_token. Returns: object
list_organizationsARead-onlyIdempotent
List accessible GMP organizations (one page, max 1000); not Google Cloud organizations.
Inputs: account, page_size, page_token. Returns: object
list_sa360_custom_columnsCRead-onlyIdempotent
List custom columns available to an SA360 customer.
Inputs: customer_id (required), account, login_customer_id. Returns: object
list_sa360_customersARead-onlyIdempotent
List directly accessible SA360 customer resource names. Use get_sa360_customer_clients on a manager to discover child accounts; this list does not include every child.
Inputs: account. Returns: object
query_sa360ARead-onlyIdempotent
Run a read-only Search Ads 360 SELECT query and return one page (max 10000).
Use bare numeric customer IDs without hyphens; login_customer_id selects a manager. Google validates selectable fields and metric compatibility. Use search_sa360_fields to discover fields. Preserve the query and other arguments for nextPageToken.
Inputs: query (required), customer_id (required), account, page_size, +2 more. Returns: object
read_dv360_report_rowsARead-onlyIdempotent
Read generated DV360 CSV values (up to 1000 raw CSV records per call, 10 MiB file).
Fetches the report URL only from Google's authenticated metadata. Returns state/ready without downloading if not DONE. Non-CSV reports are unsupported. Follow next_row_offset with the same query/report IDs. Each call downloads the bounded file again. Records include headers, totals and footer metadata; these are not all performance rows. Values stay strings to preserve precision, units and currency. No arbitrary URL input.
Inputs: query_id (required), report_id (required), account, max_rows, +1 more. Returns: object
run_dv360_reportA
Start an asynchronous DV360 report run; never changes campaigns or its definition.
Omitted dates use the saved query's range. Both dates override this run only. Returns Google's report key/status: check get_dv360_report until DONE, then use read_dv360_report_rows. FAILED is terminal. Do not poll in a tight loop. Existing query notification settings apply. After timeout, list runs before retrying because Google may already have started the run. Never automatically retry this write.
Inputs: query_id (required), account, end_date, start_date. Returns: object
search_sa360_fieldsBRead-onlyIdempotent
Discover SA360 query fields and compatibility using a metadata SELECT without FROM.
Example: SELECT name, category, selectable, filterable WHERE name LIKE 'metrics.%'
Inputs: query (required), account, page_size, page_token. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Tools are named product+resource+action, so DV360 vs CM360 vs SA360 variants are easy to keep apart, and the report-query/report-run/report-rows trio is explicitly differentiated in descriptions. The one real overlap is the local trio: connection_status and health_check both describe checking local config/token status with no network call, and authenticate adds another closely-related option.
Almost everything follows snake_case verb_noun with a domain token (list_dv360_line_items, get_cm360_creative, query_sa360, read_dv360_report_rows), which is highly predictable. The only deviations are connection_status, health_check and authenticate, which drop the verb prefix, but they read clearly as local auth utilities.
33 tools is heavy in absolute terms, but it spans four distinct Google products (DV360, CM360, SA360, GMP org) plus auth, so roughly 6-8 tools per domain is not unreasonable. Still, some list-only tools (insertion orders, line items, campaigns) pad the surface without matching get/create counterparts.
The DV360 reporting lifecycle (create query, run, list queries, list runs, poll status, read rows) and SA360's flexible query_sa360 plus field discovery give solid coverage for a read-only server. Gaps remain: CM360 has no way to create/run a report (only list definitions and fetch existing files), and DV360 campaigns/line items/insertion orders have list but no get-single detail.
Maintenance
Related MCP Connectors
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Read-only Search Console analytics, URL inspection, indexing diagnostics, and sitemaps.
Read-only access to InfluSense influencer discovery, ratings, watchlists, and reports via MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides read-only access to Google Ads account data including campaigns, ad groups, keywords, and performance reports. Enables querying via GAQL through an MCP interface.MIT
- AlicenseNot gradedqualityCmaintenanceRead-only access to Google Analytics 4 reporting data, including traffic overview, top pages, traffic sources, and conversion events, supporting custom report queries via MCP.MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only access to Google Analytics 4 and Google Search Console data, allowing users to run reports, query search analytics, and generate combined snapshots for reporting.-
- AlicenseNot gradedqualityBmaintenanceEnables read-only inspection of Google Ads accounts through MCP, including account inventory, reporting, metadata, change history, and safe GAQL queries.Apache 2.0