flin-google-ads-mcp
This is a read-only MCP server for Google Ads — no create, update, or delete operations are allowed. Here's what you can do:
Account & Customer Management
List all accessible customer accounts via OAuth credentials
Retrieve subaccounts under a manager (MCC) account, with optional name-based search
Campaign & Ad Structure
Get campaigns and ad groups, filterable by status or campaign ID
Retrieve ads including RSA content (headlines, descriptions, paths, final URLs)
Performance Insights
Get metrics (impressions, clicks, CTR, CPC, cost) at the campaign, ad group, ad, or account level
Supports preset date ranges (
TODAY,LAST_30_DAYS,THIS_MONTH, etc.) and customYYYY-MM-DDranges
Conversion Insights
View conversion-specific reporting segmented by day or conversion action
Keywords & Search Terms
Retrieve keyword-level entities with performance metrics
Fetch actual user search terms from the search term view
Change History
View recent account changes (resource, operation, old/new values) within a 30-day window
Authentication
Check OAuth status, generate an authorization URL, save a refresh token from an auth code, and clear stored tokens
Health Check
Verify server configuration and connectivity to the Google Ads API
Read-only access to Google Ads, providing tools for listing customers, campaigns, ad groups, ads, keywords, and insights (metrics) at various levels such as campaign, ad group, ad, customer, and account.
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-google-ads-mcp get yesterday's account-level insights"
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-ads-mcp
Read-only Google Ads reporting in Claude Desktop.
Start on Mac (Apple Silicon M1 or newer)
Download the Mac extension. The same package also supports Intel Macs.
In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension… and select the
.mcpbfile. Use a Claude version supporting the MCPB UV runtime.Enter the OAuth Desktop app client ID and client secret supplied by your administrator/password manager. Customer and manager IDs are optional. An existing refresh token belongs in its sensitive settings field, never in chat.
Enable the extension. Without an existing token, ask Claude to run
get_auth_url, open the Google link on this Mac and sign in. The callback saves the token automatically; no URL/code copying is needed.Run
connection_statusfor a local setup check, thenconnection_status(check_live=true)to test Google Ads access. Runlist_accessible_customers, select your account and ask forget_campaignswith that customer ID andlimit=5.
The extension version describes the installed starter/settings. connection_status.server_version is the running server version. The new starter updates to stable >=0.1.13,<0.2 servers at the next restart; it excludes prereleases. Running sessions, settings and local tokens are preserved. Import the current package once to remove the old developer-token field and give older starters this boundary; future starter/UI changes can also require an import. Existing 0.1.12 starters still receive this server update; 0.1.10/0.1.11 starters do too, but have no upper version bound.
Internet is required at startup. There is no automatic offline fallback. See setup, update limits and recovery; versioned packages remain on the release page.
Related MCP server: Google Ads MCP Server
Why this server
Read-only by design
No create/update/delete campaign operations
Browser sign-in automatically captures and stores the refresh token; access tokens renew automatically
Easy local testing with MCP Inspector
Exposed MCP tools
connection_status(local by default; optional explicit live check)health_checklist_accessible_customersget_customer_clientsfind_customer_clientsget_campaignsget_ad_groupsget_adsget_insightsget_conversion_insightsget_keywordsget_search_termsget_change_eventsauth_statusget_auth_urlsave_refresh_token_from_codeclear_auth_token
get_ads includes RSA content fields (headlines/descriptions/paths/final URLs) when available.
get_insights supports:
campaignad_groupadcustomer(account-level metrics)account(alias ofcustomer)
get_search_terms is backed by search_term_view, so it returns actual user search terms rather than configured keywords. Pass segment_by_date=true when you need daily search-term rows with a date field instead of one aggregate row per search term for the requested range.
Search-term conversion filters:
conversion_action_idconversion_action_name
Search-term optional segmentation:
segment_by_date
get_change_events is backed by the Google Ads change_event resource. It returns recent account changes with user, client type, changed resource, operation, changed field paths, and old/new values where the API returns them. Google Ads requires a finite change_event.change_date_time window within the past 30 days and a LIMIT; pass start_date and end_date as YYYY-MM-DD.
Example:
{
"tool": "get_change_events",
"args": {
"customer_id": "1234567890",
"login_customer_id": "0987654321",
"start_date": "2026-06-01",
"end_date": "2026-06-15",
"resource_type": "CAMPAIGN",
"limit": 50
}
}Conversion insights
Use get_conversion_insights when you need conversion-only reporting by day or conversion action, for example "which campaigns had lead conversions each day last week."
It supports the same levels as get_insights:
campaignad_groupadcustomer(account-level metrics)account(alias ofcustomer)
Optional segmentation:
segment_by_datesegment_by_conversion_action
Optional conversion-action filters:
conversion_action_idconversion_action_name
Rules:
pass at most one of the two parameters
conversion_action_idmust be a Google Ads resource name such ascustomers/1234567890/conversionActions/555conversion_action_namematchessegments.conversion_action_nameget_conversion_insightsreturns onlymetrics.conversionsandmetrics.conversions_value
Use get_insights for general performance metrics such as impressions, clicks, CTR, CPC, and cost. Use get_conversion_insights for conversion-action or daily conversion breakdowns.
Developer requirements
Python 3.10+
Node.js v25.8.1+ (only for MCP Inspector testing)
Google Ads API credentials:
GOOGLE_ADS_CLIENT_IDGOOGLE_ADS_CLIENT_SECRET
No developer token is required. Google sunset developer tokens on September 9, 2026; API access is managed by the Google Cloud project that owns these OAuth credentials. Enable the Google Ads API in that project and verify its access level in the Google Cloud Console. Production accounts require Explorer access or higher, as well as the signed-in user's Google Ads account permissions.
Server 0.1.13 and later ignore any existing GOOGLE_ADS_DEVELOPER_TOKEN setting, so old configurations keep working. You can remove it without changing your OAuth credentials or saved refresh token. The included google-ads>=35.0.0,<36 SDK supports requests without a developer token.
Optional:
GOOGLE_ADS_REFRESH_TOKEN(backwards-compatible override; normally generated with MCP auth tools)GOOGLE_ADS_AUTH_FILE(defaults to~/.config/flin-google-ads-mcp/auth.json)GOOGLE_ADS_OAUTH_REDIRECT_URI(optional loopback callback override; automatic sign-in defaults tohttp://127.0.0.1:<available-port>/)GOOGLE_ADS_LOGIN_CUSTOMER_IDGOOGLE_ADS_CUSTOMER_ID(default customer if nocustomer_idargument is passed)GOOGLE_ADS_USE_PROTO_PLUS(trueby default)
For MCC flows, you can also pass login_customer_id directly per tool call.
Auth flow
The MCP client config no longer needs GOOGLE_ADS_REFRESH_TOKEN.
Configure
GOOGLE_ADS_CLIENT_IDandGOOGLE_ADS_CLIENT_SECRET.Run
auth_status.If it reports
missing_refresh_token, runget_auth_url.Open the returned Google URL in a browser on the same computer and sign in within 10 minutes, keeping the MCP server running. The local callback captures the code and stores the refresh token automatically. Wait for the browser success message; no copying is required.
Run
connection_status, thenconnection_status(check_live=true)andlist_accessible_customersto verify live account access. Choose the customer account for your first report.
The stored refresh token is written to ~/.config/flin-google-ads-mcp/auth.json by default and is never returned by MCP tools. The Google client automatically renews access tokens using that refresh token. Stored credentials survive restarts; expired or revoked refresh tokens require another browser sign-in.
auth_status includes oauth_flow_status for pending, successful, denied, expired or failed sign-ins. A new get_auth_url cancels the previous flow. The temporary HTTP receiver binds only to loopback, validates state and PKCE, and closes after completion or ten minutes. clear_auth_token also cancels pending sign-in. A configured callback port must be free; leave GOOGLE_ADS_OAUTH_REDIRECT_URI unset to select an available port. This automatic flow requires the browser and MCP server to run on the same computer.
An existing refresh token can still be supplied through the extension's sensitive field or GOOGLE_ADS_REFRESH_TOKEN; it takes precedence over the file, so remove a stale override before reauthorizing. save_refresh_token_from_code remains a legacy manual fallback, not a required setup step.
Quick flow: "Example Customer spend yesterday"
Find the subaccount by name under the manager:
{
"tool": "find_customer_clients",
"args": {
"manager_customer_id": "0987654321",
"login_customer_id": "0987654321",
"name_query": "Example Customer",
"direct_only": false,
"include_hidden": false,
"include_self": false,
"status": "ALL",
"limit": 50
}
}Use the returned
client_customer_idwith account-level insights:
{
"tool": "get_insights",
"args": {
"customer_id": "1234567890",
"login_customer_id": "0987654321",
"level": "account",
"date_range": "YESTERDAY",
"limit": 10
}
}Date ranges
get_insights, get_conversion_insights, get_keywords, and get_search_terms support:
TODAYYESTERDAYTHIS_WEEK_MON_TODAYTHIS_WEEK_SUN_TODAYLAST_WEEK_MON_SUNLAST_WEEK_SUN_SATLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_60_DAYSLAST_90_DAYSTHIS_MONTHLAST_MONTHCUSTOM(requiresstart_dateandend_dateinYYYY-MM-DD)
Quickstart (from source)
uv sync --extra dev
cp .env.example .env
# Fill .env values
uv run flin-google-ads-mcpQuickstart (as published package)
uvx --prerelease disallow --from "flin-google-ads-mcp>=0.1.13,<0.2" flin-google-ads-mcpDeveloper configuration (published via uvx)
{
"mcpServers": {
"flin-google-ads-mcp": {
"command": "uvx",
"args": ["--prerelease", "disallow", "--from", "flin-google-ads-mcp>=0.1.13,<0.2", "flin-google-ads-mcp"],
"env": {
"GOOGLE_ADS_CLIENT_ID": "xxx",
"GOOGLE_ADS_CLIENT_SECRET": "xxx",
"GOOGLE_ADS_CUSTOMER_ID": "1234567890",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
}
}
}
}Claude integration (local development)
{
"mcpServers": {
"flin-google-ads-mcp-local": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/flin-google-ads-mcp",
"flin-google-ads-mcp"
],
"env": {
"GOOGLE_ADS_CLIENT_ID": "xxx",
"GOOGLE_ADS_CLIENT_SECRET": "xxx",
"GOOGLE_ADS_CUSTOMER_ID": "1234567890",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "0987654321"
}
}
}
}How to test
Detailed guide: docs/testing.md
Release checklist: docs/release.md
Operational usage guide:
Fast path:
uv sync --extra dev
python3 -m pytest
python3 -m compileall srcThen run live smoke tests with MCP Inspector (see the testing guide).
Release on GitHub + PyPI
This repository publishes automatically with GitHub Actions:
CI:
.github/workflows/ci.ymlRelease:
.github/workflows/release.yml(triggered by git tagsv*)
1) Configure PyPI Trusted Publisher (one-time)
In PyPI project settings for flin-google-ads-mcp, add a Trusted Publisher with:
Owner:
flin-agencyRepository:
flin-google-ads-mcpWorkflow:
release.ymlEnvironment:
pypi
2) Cut a release
Follow the release checklist to keep the server, starter, stable download alias and published packages in sync.
Every v* release automatically builds and tests both packages, publishes to PyPI using OIDC, verifies the published files and the extension startup against PyPI, then publishes the Mac MCPB and Python packages to GitHub. See the release checklist.
CI
GitHub Actions validates:
unit tests
import/compile checks
package build
Available Tools
17 toolsauth_statusARead-only
Report whether Google Ads OAuth auth is available without exposing secrets.
Inputs: no named parameters. Returns: object
clear_auth_tokenADestructive
Delete the locally stored refresh token.
Inputs: no named parameters. Returns: object
connection_statusARead-only
Report setup without network access by default. check_live=True explicitly tests Google Ads access; no customer data is returned.
Inputs: check_live. Returns: object
find_customer_clientsCRead-only
Find subaccounts by descriptive name under a specific manager account.
Inputs: name_query (required), manager_customer_id (required), limit, status, +4 more. Returns: object
get_ad_groupsCRead-only
Get ad groups for a customer account, optionally filtered by campaign.
Inputs: limit, status, campaign_id, customer_id, +1 more. Returns: object
get_adsCRead-only
Get ads for a customer account, optionally filtered by campaign or ad group.
Inputs: limit, status, ad_group_id, campaign_id, +2 more. Returns: object
get_auth_urlA
Start automatic local OAuth capture. Open the returned URL; no code copying is needed.
Inputs: no named parameters. Returns: object
get_campaignsCRead-only
Get campaigns for a customer account.
Inputs: limit, status, customer_id, login_customer_id. Returns: object
get_change_eventsCRead-only
Get recent Google Ads account change events from the change_event resource.
Inputs: limit, end_date, start_date, user_email, +3 more. Returns: object
get_conversion_insightsCRead-only
Get conversion-only metrics with optional date and conversion-action segments.
Inputs: level, limit, end_date, date_range, +9 more. Returns: object
get_customer_clientsCRead-only
List subaccounts under a manager account using the customer_client resource.
Inputs: limit, status, customer_id, direct_only, +3 more. Returns: object
get_insightsCRead-only
Get read-only performance metrics for campaign, ad_group, or ad level.
Inputs: level, limit, end_date, date_range, +5 more. Returns: object
get_keywordsCRead-only
Get keyword-level entities and performance metrics.
Inputs: limit, status, end_date, date_range, +7 more. Returns: object
get_search_termsCRead-only
Get search-term-level entities and performance metrics.
Inputs: limit, status, end_date, date_range, +8 more. Returns: object
health_checkARead-only
Check whether required Google Ads configuration is present and client initialization works.
Inputs: no named parameters. Returns: object
list_accessible_customersARead-only
List customer IDs accessible by the configured OAuth credentials.
Google Ads API ignores login_customer_id for this specific operation.
Inputs: limit, login_customer_id. Returns: object
save_refresh_token_from_codeBDestructive
Legacy manual fallback; get_auth_url normally captures and stores the token automatically.
Inputs: code (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
The core Google Ads retrieval tools target distinct resources (campaigns, ad groups, ads, keywords, search terms, insights, change events), so those are mostly clear. However, health_check, connection_status, and auth_status overlap heavily around setup/diagnostics, and get_customer_clients versus find_customer_clients have fuzzy boundaries. get_insights and get_conversion_insights also partially overlap, though the conversion-specific description helps.
The tools use consistent snake_case, but verb conventions are mixed: get_*, list_*, find_*, save_*, clear_*, plus noun-phrase status tools like health_check and auth_status. The pattern is readable but not predictable enough for a strong consistency score.
At 17 tools, the server sits in the borderline-heavy range. The count is not unreasonable for Google Ads reporting plus OAuth setup, but the six or so auth/diagnostic tools make the surface feel larger than necessary.
For a read-only Google Ads reporting server, the surface covers the core entities and metrics: customers, campaigns, ad groups, ads, keywords, search terms, insights, conversions, and change events. Some secondary reporting areas such as budgets, bidding, and audience/geo dimensions are absent, but the main workflows are covered.
Maintenance
Related MCP Connectors
Google Ads MCP server — manage campaigns, keywords, and metrics.
Read-only Google Search Console MCP server for AI assistants.
Read-only Google Analytics 4 MCP server for AI assistants.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Related MCP Servers
- AlicenseBqualityBmaintenanceRead-only MCP server for Meta Ads that lists and reads ad accounts, campaigns, ad sets, ads, ad images, creatives, and fetches insights at various levels.18MIT
- 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
- AlicenseAqualityBmaintenanceA read-only MCP server for querying Google Ads data using GAQL, enabling AI assistants to safely read campaign performance, ad groups, and keywords.12527 PyPI2MIT
- AlicenseBqualityDmaintenanceRead-only MCP server for Google Ads API, enabling natural language queries about campaigns, metrics, search terms, and change history without write access.6MIT