google-ads-function-gateway
This server is a read-only Google Ads Function Gateway MCP server that exposes six predefined, allow-list-enforced catalogue functions for discovering and reporting on Google Ads accounts and campaigns.
List accessible Google Ads accounts under the configured MCC context.
Get details for a single explicitly allow-listed Google Ads customer.
List campaigns for a customer, optionally filtered by status, campaign IDs, channel type, or name substring.
Get details for one campaign in an allow-listed customer.
Get daily campaign cost rows for a customer over a date range, optionally filtered by status or campaign IDs.
Get campaign performance rows for one or more allow-listed customers over a date range, optionally filtered by status or campaign IDs.
Access the same capabilities through the CLI or through MCP over stdio and Streamable HTTP transports.
No write/mutation operations, no arbitrary GAQL, and reporting customer IDs must be explicitly authorized.
Provides read-only access to Google Ads reporting data through predefined functions for account details, campaign listing/details, cost, and performance metrics, with explicit customer ID authorization.
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., "@google-ads-function-gateway Show me campaign cost for customer 1112223333 from 2026-08-30 to 2026-08-30"
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.
Google Ads Function Gateway
Standalone, deterministic Google Ads function gateway for Google Ads Function Catalogue v1 Phase A and Phase B functions 01-06.
The gateway includes a stdio MCP server adapter, but it is intentionally not an MCP conversational client. MCP clients should call approved function names with validated parameters; they must not supply raw GAQL or construct Google Ads API logic at runtime.
Architecture Rules
No arbitrary GAQL endpoint.
No GAQL supplied by users, CLI callers, or MCP clients.
No runtime AI-generated Google Ads API code.
Google Ads queries remain predefined and version-controlled.
All reporting customer IDs require explicit authorization.
No mutation/write operations.
The CLI and MCP server use the same catalogue and function classes as future HTTP, cron, dashboard, and automation consumers.
Related MCP server: Google Ads MCP Server
Local Setup
A. Clone Repository
git clone https://github.com/adeshsarwan/google-ads-mcp-client.git
cd google-ads-mcp-clientB. Create Virtual Environment
python3 -m venv .venv
source .venv/bin/activateC. Install Dependencies
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"This installs the official google-ads Python client, python-dotenv, and dev tooling including ruff.
D. Create Local Environment File
cp .env.example .envNever commit .env. It is ignored by Git.
E. Configure Google Ads Credentials
Edit .env and set:
GOOGLE_ADS_DEVELOPER_TOKEN=replace-me
GOOGLE_ADS_CLIENT_ID=replace-me
GOOGLE_ADS_CLIENT_SECRET=replace-me
GOOGLE_ADS_REFRESH_TOKEN=replace-meIf you do not already have a refresh token, generate one locally:
python -m google_ads_function_gateway oauth-generate-refresh-tokenThe command reads GOOGLE_ADS_CLIENT_ID and GOOGLE_ADS_CLIENT_SECRET from .env, opens a local Google OAuth consent flow, and prints GOOGLE_ADS_REFRESH_TOKEN=... once. It does not write the token to disk.
This helper intentionally requests only the Google Ads scope and disables incremental authorization. That prevents unrelated scopes previously granted to the same Google Cloud project, such as Ad Manager, from being merged into this local Google Ads setup.
For Web Application OAuth clients, add the local loopback redirect URI in Google Cloud Console under Authorized redirect URIs. The default command uses:
http://127.0.0.1:8080/If you run the helper with --port, add the matching http://127.0.0.1:<port>/ URI. At minimum, the redirect must use http://127.0.0.1; localhost is not the host used by this helper.
F. Configure Login MCC
GOOGLE_ADS_LOGIN_CUSTOMER_ID is the manager/MCC account used as the discovery root:
GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890The login customer ID is not the same as a reporting customer ID. It identifies the manager account context for Google Ads API access and account discovery.
G. Run Doctor
python -m google_ads_function_gateway doctorDoctor prints readiness statuses and package/API version details without printing secrets.
H. Discover Accounts
python -m google_ads_function_gateway list-accountsDiscovery can list child accounts under the configured MCC even before those child accounts are in GOOGLE_ADS_ALLOWED_CUSTOMER_IDS. Discovery does not grant reporting authorization.
I. Authorize Selected Customer IDs
Choose customer IDs from discovery output and add them to the allow-list:
GOOGLE_ADS_ALLOWED_CUSTOMER_IDS=1112223333,4445556666Reporting functions fail closed until the target customer ID is explicitly listed here.
J. Run Standardized Functions
python -m google_ads_function_gateway get-account-details \
--customer-id 1112223333
python -m google_ads_function_gateway list-campaigns \
--customer-id 1112223333
python -m google_ads_function_gateway get-campaign-details \
--customer-id 1112223333 \
--campaign-id 987654321
python -m google_ads_function_gateway get-campaign-cost \
--customer-id 1112223333 \
--start-date 2026-08-30 \
--end-date 2026-08-30
python -m google_ads_function_gateway get-campaign-performance \
--customer-id 1112223333 \
--start-date 2026-08-30 \
--end-date 2026-08-30Each command prints the normalized JSON envelope returned by the catalogue.
MCP Transports
The MCP server exposes only the six existing read-only catalogue functions through both stdio and Streamable HTTP. Both transports use the same MCP server object, tool handlers, and Google Ads Function Catalogue. They do not add conversational routing, caller-supplied GAQL, direct HTTP Google Ads calls, or write operations.
Install the project into the local virtual environment first:
source .venv/bin/activate
python -m pip install -e ".[dev]"Local Stdio Mode
Configure a local MCP client to launch the stdio server from the project root. The client configuration should contain only the executable, arguments, working directory if supported, and non-secret runtime options:
{
"mcpServers": {
"google-ads-function-gateway": {
"command": "/absolute/path/to/google-ads-mcp-client/.venv/bin/python",
"args": ["-m", "google_ads_function_gateway.mcp_server"],
"cwd": "/absolute/path/to/google-ads-mcp-client"
}
}
}Local Streamable HTTP Mode
Streamable HTTP uses OAuth by default because it is the remote-capable mode intended
for ChatGPT Custom Apps. Set the OAuth environment in the server-side .env first:
GOOGLE_ADS_MCP_AUTH_MODE=oauth
GOOGLE_ADS_MCP_PUBLIC_HOST=googleads-mcp.thebesads.com
GOOGLE_ADS_MCP_PUBLIC_ORIGIN=https://googleads-mcp.thebesads.com
GOOGLE_ADS_MCP_OAUTH_DB=/var/lib/google-ads-mcp/oauth.db
GOOGLE_ADS_MCP_OWNER_USERNAME=replace-me
GOOGLE_ADS_MCP_OWNER_PASSWORD_HASH=replace-with-argon2id-hash
GOOGLE_ADS_MCP_OAUTH_SECRET=replace-with-at-least-32-random-chars
GOOGLE_ADS_MCP_ACCESS_TOKEN_TTL_SECONDS=3600
GOOGLE_ADS_MCP_AUTH_CODE_TTL_SECONDS=300
GOOGLE_ADS_MCP_REFRESH_TOKEN_TTL_SECONDS=2592000
GOOGLE_ADS_MCP_HTTP_DIAGNOSTICS=0Generate the owner password hash locally without printing the plaintext password:
python - <<'PY'
from argon2 import PasswordHasher
from getpass import getpass
print(PasswordHasher().hash(getpass("Owner password: ")))
PYStart the Streamable HTTP MCP endpoint:
GOOGLE_ADS_MCP_HOST=127.0.0.1 GOOGLE_ADS_MCP_PORT=8000 \
python -m google_ads_function_gateway.mcp_server --transport streamable-httpDefault endpoint:
http://127.0.0.1:8000/mcpThe server defaults to 127.0.0.1 for safety. OAuth discovery endpoints are exposed
by the same process:
https://googleads-mcp.thebesads.com/.well-known/oauth-protected-resource/mcp
https://googleads-mcp.thebesads.com/.well-known/oauth-authorization-server
https://googleads-mcp.thebesads.com/oauth/authorize
https://googleads-mcp.thebesads.com/oauth/token
https://googleads-mcp.thebesads.com/oauth/register
https://googleads-mcp.thebesads.com/oauth/revokeThe OAuth server supports authorization code with PKCE S256 and refresh-token grant. It does not support the implicit grant. The MCP resource scope is:
google_ads.readoffline_access may be requested when the client needs refresh tokens.
OAuth mode is intentionally ChatGPT-compatible mixed authentication. The MCP
initialize, notifications/initialized, and tools/list protocol messages can
run without an access token so ChatGPT can scan and publish the six tool
descriptors before the owner completes OAuth. Every tools/call for the Google
Ads catalogue still requires a valid MCP OAuth access token with google_ads.read;
missing, invalid, or under-scoped tokens return an MCP auth challenge via
_meta["mcp/www_authenticate"] and do not execute Google Ads code.
ChatGPT Business Custom App discovery may first send an unauthenticated empty
POST /mcp reachability probe with Content-Length: 0 before it fetches OAuth
metadata or sends MCP JSON-RPC. In OAuth mode, the server answers only that
exact empty probe with 401 Unauthorized and a WWW-Authenticate challenge
pointing to the protected-resource metadata. It does not create an MCP session,
authenticate the request, issue OAuth tokens, or execute tools. Any POST
containing MCP headers, authorization, a session ID, malformed JSON, a JSON-RPC
batch, or a non-empty body continues through the SDK's strict MCP validation
path.
OAuth owner approval happens on server-hosted login and approval pages. The password
stored in .env must be an Argon2id hash in GOOGLE_ADS_MCP_OWNER_PASSWORD_HASH;
do not put a plaintext owner password in .env.
The MCP transport endpoint keeps the SDK Host/Origin/DNS-rebinding checks. OAuth metadata and browser authorization routes keep exact Host allowlisting but do not inherit the MCP transport Origin rule; they are protected by OAuth request state, exact redirect URI matching, PKCE, CSRF tokens, and owner-session cookies.
For a local protocol-only smoke test without OAuth, explicitly choose the fallback mode:
GOOGLE_ADS_MCP_AUTH_MODE=static_bearer \
python -m google_ads_function_gateway.mcp_server --transport streamable-httpExample local MCP protocol smoke test in fallback mode:
curl -i http://127.0.0.1:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-smoke","version":"0"}}}'To use the legacy static bearer fallback, set both:
GOOGLE_ADS_MCP_AUTH_MODE=static_bearer
GOOGLE_ADS_MCP_AUTH_TOKEN=replace-with-a-long-random-tokenThen add this header to MCP requests:
-H "Authorization: Bearer $GOOGLE_ADS_MCP_AUTH_TOKEN"OAuth mode ignores GOOGLE_ADS_MCP_AUTH_TOKEN.
Secret Handling
Do not place GOOGLE_ADS_DEVELOPER_TOKEN, OAuth client secrets, refresh tokens, or any other Google Ads credentials in MCP client JSON or remote connector settings. The MCP server uses the same load_local_env() mechanism as the CLI and loads the ignored .env file from the project root.
Google Ads credentials stay server-side and are never provided to ChatGPT. If you expose the Streamable HTTP endpoint through a secure tunnel or HTTPS reverse proxy, ChatGPT connects only to the MCP protocol endpoint and completes OAuth with this MCP service.
MCP stdio reserves stdout for JSON-RPC protocol messages. The MCP entrypoint does not print banners or debug output, and operational logging is configured for stderr.
Set GOOGLE_ADS_MCP_HTTP_DIAGNOSTICS=1 only when diagnosing remote MCP
connectivity. It logs secret-free request facts such as path, HTTP status,
Content-Type, Accept, User-Agent, Content-Length, MCP session/protocol header
presence, MCP method header, JSON top-level type, JSON-RPC version, JSON-RPC id
type, parse-failure category, and duration to stderr. It also logs safe OAuth
metadata for /oauth/register and /oauth/authorize, including redirect URIs,
scope names, grant/response types, token endpoint auth method, client name,
software ID, status, and booleans for whether a client ID or client secret was
issued. It never logs Authorization header values, cookies, OAuth client secrets,
authorization codes, OAuth tokens, owner passwords, Google Ads credentials, raw
request parameters, or response data.
Tunnel Compatibility
The Streamable HTTP server is designed to sit behind a standard HTTPS reverse proxy or secure tunnel. Keep the local server bound to 127.0.0.1, expose the MCP and OAuth paths over HTTPS, and ensure the proxy forwards request bodies and MCP headers unchanged. The application does not depend on a specific tunnel vendor.
The MCP Python SDK keeps DNS-rebinding protection enabled for Streamable HTTP. When deploying behind Cloudflare Tunnel or another HTTPS reverse proxy, set the public hostname so the forwarded Host header is explicitly allowed:
GOOGLE_ADS_MCP_PUBLIC_HOST=googleads-mcp.thebesads.comCurrent production MCP endpoint:
https://googleads-mcp.thebesads.com/mcpThe production origin allowlist is limited to https://googleads-mcp.thebesads.com when an Origin header is present.
For ChatGPT Business Custom Apps, configure:
MCP server URL:
https://googleads-mcp.thebesads.com/mcpAuthentication: OAuth
Scopes:
google_ads.read offline_access
ChatGPT receives OAuth access and refresh tokens for this MCP server only. It does not receive the Google Ads developer token, Google OAuth client secret, Google Ads refresh token, or any other server-side Google Ads credential.
Dynamic client registration is enabled so ChatGPT can register its exact redirect URI and use PKCE S256 during account linking.
When the ChatGPT Business app scans actions, it should be able to import the same six tools before the owner OAuth login happens. OAuth is enforced when ChatGPT or another MCP client calls a tool, not when it lists tool descriptors.
Configuration
Supported environment variables:
GOOGLE_ADS_DEVELOPER_TOKENGOOGLE_ADS_CLIENT_IDGOOGLE_ADS_CLIENT_SECRETGOOGLE_ADS_REFRESH_TOKENGOOGLE_ADS_LOGIN_CUSTOMER_IDGOOGLE_ADS_ALLOWED_CUSTOMER_IDSGOOGLE_ADS_API_VERSIONoptional; when omitted, the gateway uses the highest API version packaged bygoogle-ads-pythonGOOGLE_ADS_RETRY_ATTEMPTSoptional, default3GOOGLE_ADS_RUN_LIVE_TESTSoptional; set to1only when intentionally running live read-only testsGOOGLE_ADS_MCP_HOSToptional Streamable HTTP bind host, default127.0.0.1GOOGLE_ADS_MCP_PORToptional Streamable HTTP bind port, default8000GOOGLE_ADS_MCP_PUBLIC_HOSToptional public HTTPS tunnel or reverse-proxy hostname allowed by MCP DNS-rebinding protectionGOOGLE_ADS_MCP_PUBLIC_ORIGINoptional explicit OAuth issuer/origin; defaults tohttps://GOOGLE_ADS_MCP_PUBLIC_HOSTwhen a public host is configuredGOOGLE_ADS_MCP_AUTH_MODEoptional Streamable HTTP auth mode, defaultoauth; set tostatic_beareronly for the legacy bearer-token fallbackGOOGLE_ADS_MCP_OAUTH_DBSQLite OAuth persistence path, default/var/lib/google-ads-mcp/oauth.dbGOOGLE_ADS_MCP_OWNER_USERNAMEOAuth owner approval usernameGOOGLE_ADS_MCP_OWNER_PASSWORD_HASHArgon2id hash for the OAuth owner approval passwordGOOGLE_ADS_MCP_ACCESS_TOKEN_TTL_SECONDSOAuth access-token lifetime, default3600GOOGLE_ADS_MCP_AUTH_CODE_TTL_SECONDSOAuth authorization-code lifetime, default300GOOGLE_ADS_MCP_REFRESH_TOKEN_TTL_SECONDSOAuth refresh-token lifetime, default2592000GOOGLE_ADS_MCP_OAUTH_SECRETserver-side HMAC secret for hashing OAuth tokens, authorization codes, client secrets, and owner sessions at restGOOGLE_ADS_MCP_HTTP_DIAGNOSTICSoptional secret-free Streamable HTTP diagnostic logging, default0GOOGLE_ADS_MCP_AUTH_TOKENoptional bearer token used only whenGOOGLE_ADS_MCP_AUTH_MODE=static_bearer
Development Checks
python -m compileall src tests
python -m unittest discover -s tests
ruff check .Live Smoke Tests
Live tests are opt-in and read-only. They never run unless this flag is set:
GOOGLE_ADS_RUN_LIVE_TESTS=1 python -m unittest tests.integration.test_live_google_ads_smokeThe tests require valid credentials, a configured login MCC when using MCC discovery, and at least one explicitly allowed reporting customer ID.
Available Tools
6 toolsget_account_detailsARead-onlyIdempotent
Return details for one explicitly allow-listed Google Ads customer.
Inputs: customer_id (required).
get_campaign_costARead-onlyIdempotent
Return daily campaign cost rows for an explicitly allow-listed customer.
Inputs: end_date (required), start_date (required), customer_id (required), status, +1 more.
get_campaign_detailsBRead-onlyIdempotent
Return details for one campaign in an explicitly allow-listed customer.
Inputs: campaign_id (required), customer_id (required).
get_campaign_performanceCRead-onlyIdempotent
Return campaign performance rows for one or more explicitly allow-listed customers.
Inputs: end_date (required), start_date (required), status, customer_id, +2 more.
list_accountsARead-onlyIdempotent
Discover accessible Google Ads accounts using the configured MCC context.
Inputs: no named parameters.
list_campaignsARead-onlyIdempotent
List campaigns for one explicitly allow-listed Google Ads customer.
Inputs: customer_id (required), status, campaign_ids, channel_type, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tools are mostly distinct: list vs details pairs for accounts and campaigns are clear, and cost vs performance have separate purposes. There is minor potential confusion between get_campaign_cost and get_campaign_performance since cost could be considered part of performance, but the descriptions clarify the difference.
All tool names follow a consistent verb_noun pattern with snake_case, such as list_accounts, get_account_details, and list_campaigns. The naming is predictable and makes the tool's purpose clear.
Six tools is a well-scoped set for a Google Ads read-only gateway. Each tool covers a meaningful access or reporting need without unnecessary redundancy.
The tool surface covers core account discovery, campaign listing, details, cost, and performance reporting. It lacks deeper campaign management or ad-level reporting, but for a read-only function gateway the major workflows are covered.
Maintenance
Related MCP Connectors
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Read-only MCP connector for Adlane workspaces, Google and Meta ad accounts and campaign reports.
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Microsoft Ads MCP server: 11 tools for search, PMax, Google Ads imports. Read-only by default.
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
- FlicenseNot gradedqualityCmaintenanceA read-only MCP server for the Google Ads API, exposing reporting tools for account summaries, campaigns, performance, search terms, and conversion actions. Enables natural-language queries to Google Ads data without write access.-
- FlicenseNot gradedqualityCmaintenanceEnables management of Google Ads accounts via MCP, providing read and write tools for campaigns, ad groups, keywords, assets, and more, with support for reporting and mutations.-
- AlicenseNot gradedqualityCmaintenanceEnables Claude, ChatGPT, Copilot, and Cursor to read Google Ads data—campaigns, ad groups, ads, keywords, search terms, budgets, conversion actions, change history, and custom GAQL queries—through 17 read-only MCP tools. It supports OAuth-authenticated access to real accounts without requiring a developer token, keeping all operations read-only and auditable.58 npmAGPL 3.0