google-ads-mcp
Connects an MCP client to the Google Ads API using service-account authentication. Provides GAQL reporting tools for reading accounts, campaigns, budgets, ad groups, ads, keywords, search terms, segments (geo/device/network/time), assets and extensions, conversions, recommendations, policy, bidding, billing, experiments, audiences, Performance Max and shopping/video/display/search campaigns, plus convenience write tools for campaigns, budgets, bidding, ad groups, keywords and negatives, targeting, responsive search ads, assets, conversion uploads, audiences/user lists, experiments, labels, billing setup, and batch jobs. Also exposes generic, future-proof tools such as google_ads_query, google_ads_mutate, google_ads_batch_mutate, google_ads_resource_mutate, google_ads_service_call, google_ads_list_services, and google_ads_batch_job, with dry-run validation and budget/bid change guardrails.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
google-ads-mcp
Production-ready remote MCP server that connects ChatGPT Business (or any MCP client) to the Google Ads API using service-account authentication.
Built for the Myth Nightclub Google Ads account with conservative initial usage (monitoring, reporting, small approved optimizations), while exposing broad generic read/mutate capabilities so you do not need to redesign the connector later.
Stack
Python 3.12
FastMCP (HTTP / Streamable MCP)
Official
google-adsPython client (uses the library's current default API version, e.g. v25 withgoogle-ads32.x)Uvicorn ASGI on Railway
Related MCP server: Google Ads MCP Server
Endpoints
Path | Auth | Purpose |
| None | Health check (no secrets) |
|
| MCP transport |
Environment variables
GOOGLE_ADS_CUSTOMER_ID=
GOOGLE_ADS_LOGIN_CUSTOMER_ID=
GOOGLE_SERVICE_ACCOUNT_JSON=
MCP_API_KEY=
MCP_TOOL_MODE=compact
MAX_BUDGET_CHANGE_PERCENT=15
MAX_BID_CHANGE_PERCENT=15
PORT=Notes:
MCP_TOOL_MODEcontrols how many tools ChatGPT sees at the MCP layer (defaultcompact). All tools remain implemented in code;fullexposes every registered tool (~200+).GOOGLE_ADS_CUSTOMER_IDmust be 10 digits, numbers only (no hyphens). Hyphens in input are stripped automatically.GOOGLE_ADS_LOGIN_CUSTOMER_IDis optional (use for MCC / manager access).GOOGLE_SERVICE_ACCOUNT_JSONis the full service account JSON as one variable. Escaped\ninsideprivate_keyis supported.Developer token is not required for this deployment model (Google Cloud project API access level controls production access).
Secrets are never logged.
Local development
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export GOOGLE_ADS_CUSTOMER_ID=XXXXXXXXXX
export GOOGLE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'
export MCP_API_KEY=your-secret
uvicorn app.server:app --host 0.0.0.0 --port 8000Run tests:
pytestRailway deployment
Create a new Railway project from this repository.
Set Root Directory to repo root (contains
Dockerfile).Add environment variables from
.env.example(paste service account JSON intoGOOGLE_SERVICE_ACCOUNT_JSON).Railway sets
PORTautomatically; the container listens on0.0.0.0:$PORT.Deploy and verify:
GET https://<your-app>.up.railway.app/health
Configure ChatGPT Business MCP:
URL:
https://<your-app>.up.railway.app/mcpHeader:
Authorization: Bearer <MCP_API_KEY>
Railway checklist
Service account has Standard access on the Google Ads account
Google Cloud project has Google Ads API enabled with appropriate access level
GOOGLE_ADS_CUSTOMER_IDset (Myth Nightclub account, digits only)MCP_API_KEYset to a long random secret/healthreturns{"status":"ok",...}
MCP tool exposure modes
Mode | Env value | Behavior |
Compact (default) |
| Exposes ~60 high-value read/write/remove tools plus generic API tools ( |
Full |
| Exposes every implemented tool for advanced operators. |
GET /health includes mcp_tool_mode, tools_exposed, and tools_implemented.
Safety controls
All mutation tools support:
dry_run: bool— usesvalidate_onlywhen the API supports itoverride_limits: bool— bypasses convenience budget/bid guardrails
Environment guardrails (convenience tools):
MAX_BUDGET_CHANGE_PERCENTMAX_BID_CHANGE_PERCENT
Generic raw mutation tools (google_ads_mutate, google_ads_service_call, etc.) emit a limit warning when guardrails are configured but not overridden.
Remove operations always return an explicit remove summary (resource name + customer ID).
Architecture
app/
server.py # FastMCP + /health + ASGI app
auth.py # Service account JSON parsing
config.py # Environment settings
google_ads_client.py # Client factory + GAQL execution
gaql.py # GAQL validation
errors.py # Google Ads error formatting
audit.py # Structured stdout audit logs
safety.py # Budget/bid limits
mutations.py # Generic mutate + service call dispatch
services_registry.py # Dynamic service/method allowlist
tools/
raw_api.py # Generic/future-proof tools
reporting.py # GAQL convenience reads
campaigns.py ... # Domain write toolsTool surface (summary)
Generic / future-proof
google_ads_querygoogle_ads_describe_fieldsgoogle_ads_list_servicesgoogle_ads_service_callgoogle_ads_mutategoogle_ads_batch_mutate/google_ads_multi_mutategoogle_ads_resource_mutategoogle_ads_batch_job
Convenience reads (GAQL)
Account, campaigns, budgets, ad groups, ads, keywords, search terms, segments (geo/device/network/time), assets & extensions, conversions, recommendations, policy, bidding, billing, experiments, audiences, Performance Max, shopping/video/display/search campaign filters, negatives, labels, geo/language constants, etc. (see tools/reporting.py).
Convenience writes
Campaigns, budgets, bidding, ad groups, keywords/negatives, targeting, ads (RSA), assets, conversions upload, recommendations, audiences/user lists, Performance Max, experiments, labels, billing setup, batch jobs.
Use google_ads_list_services + google_ads_service_call for any additional Google Ads service methods not wrapped by a named convenience tool.
Known API Coverage Gaps
Keyword Plan Idea / historical metrics: use
google_ads_service_callwithKeywordPlanIdeaService(not full GAQL).Customer Match member removal: requires
OfflineUserDataJobServicejob workflow; helper returns guidance.Invoices:
invoiceis not aGoogleAdsServiceGAQL resource in API v25.get_invoices_if_supportedreturns guidance; useInvoiceService.list_invoicesviagoogle_ads_service_call(billing setup + issue month; may require elevated access).conversion_goalresource: removed. Convenience reads usecustom_conversion_goal(pluscampaign_conversion_goal/customer_conversion_goal). The newergoalresource is not wrapped as a named convenience tool.campaign_experimentresource: removed. Useexperimentandexperiment_arm.Combined age + gender demographics: not supported in one GAQL query.
get_demographic_performanceusesgender_viewonly; queryage_range_viewseparately viagoogle_ads_query.Asset / listing metrics: some
FROM assetmetric combinations can be rejected by the live API even when fields exist on the proto. Errors are returned verbatim — do not assume every convenience report is selectable together.Per-service named wrappers: all installed services are reachable via
google_ads_service_call; not every service has a dedicated convenience alias.Explorer access limitations: write or specialized endpoints may fail until Google Cloud API access is upgraded — errors include suggested actions.
Resource mutate dispatcher: maps to the primary
mutate_*method per service; exotic operation shapes may requiregoogle_ads_service_callwith an explicit request payload.
Audit logging
Structured JSON logs for write operations go to stdout (Railway log retention), including tool name, customer ID, dry-run flag, resource names, success/failure, and Google request ID when available. Secrets are not logged.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Manage Google Ads from ChatGPT, Claude or any MCP client. Sign in with OAuth or use an API key.
Hosted Google Ads MCP for Claude and ChatGPT. Preview every write. No developer token.
Google Ads MCP server — manage campaigns, keywords, and metrics.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server that lets any LLM manage Google Ads campaigns from the terminal. Supports read and write operations.-
- AlicenseNot gradedqualityFmaintenanceMCP server for Google Ads API that enables LLMs to search and query Google Ads accounts, retrieve resource metadata, and generate keyword ideas.Apache 2.0
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that exposes the Google Ads API to LLM clients, enabling account inspection, GAQL queries, performance reporting, and campaign management.-
- AlicenseAqualityBmaintenanceAn MCP server that enables safe, audited mutation of Google Ads campaigns—creating ads, ad groups, keywords, and assets or adjusting budgets and statuses—with a dry-run default and an optional guarded remove operation, plus read-only Keyword Planner ideas.222MIT