Google Ads

You can run a TypeScript MCP server that interfaces with the Google Ads API, enabling MCC-style management, campaign operations, and performance reporting in a multi-tenant or single-tenant setup. This guide shows practical steps to install, configure, and use the server with MCP clients, so you can connect your apps to Google Ads data securely and efficiently.

How to use

You will start the server using an MCP client, choose whether to run it directly via an MCP runner (such as npx) or from a local build, and then connect your client to the server using the provided environment variables. You can set a default Google Ads account, optionally specify a manager (MCC) account, and supply your developer token. Use the server to list resources, run GAQL queries, and retrieve performance data at various levels (account, campaign, ad group, ad, keyword). In multi-tenant mode you can establish per-session credentials and execute operations within the scope of that session.

How to install

Prerequisites: Node.js 18+ and npm, plus a Google Cloud project with the Google Ads API enabled. You should also have a Google Ads Developer Token and credentials that can access the API.

Step by step install and run when using the recommended npx approach:

{
  "mcpServers": {
    "google-ads": {
      "command": "npx", 
      "args": ["mcp-google-ads-ts"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEV_TOKEN",       // Required: Your Google Ads Developer Token
        "GOOGLE_ADS_ACCOUNT_ID": "1234567890",                // Optional: Default customer ID
        "GOOGLE_ADS_MANAGER_ACCOUNT_ID": "9876543210"         // Optional: MCC account ID for login
      }
    }
  }
}

Additional configuration and setup

Environment variables control authentication, API version, and quota project. You can enable MCC-specific behavior, specify a default date range for reports, and configure observability. The following variables are commonly used:

• GOOGLE_ADS_DEVELOPER_TOKEN (required) — your Google Ads developer token.

• GOOGLE_ADS_ACCOUNT_ID — default customer ID (10 digits, no dashes).

• GOOGLE_ADS_MANAGER_ACCOUNT_ID — MCC account ID for login when accessing MCC-linked accounts.

• GOOGLE_APPLICATION_CREDENTIALS — path to ADC file if you are using ADC for authentication.

• GOOGLE_ADS_API_VERSION — API version (defaults to v21 if not set).

• OBSERVABILITY or OBSERVABILITY_ENABLED — control structured logging. Set to off or false to disable.

Security and multi-tenant notes

In multi-tenant mode you will provide credentials per session. A session is immutable for its lifetime. Credentials must include a developer token, and you pass a session_key with each operation. You can also refresh access tokens for active sessions when using the right OAuth flow.

Troubleshooting and tips

If authentication fails, verify ADC or CLI-based credentials are available and have the needed Google Ads scopes. Ensure the developer token is correct and that quota project is configured to avoid 403 errors. For MCC usage, confirm the login_customer_id matches the account structure you intend to access.

Available tools

manage_auth

Authentication management tool that handles status checks, OAuth login, and credential switching. In multi-tenant mode, this tool is disabled in favor of per-session credential tools.

list_resources

Lists Google Ads resources such as accounts, campaigns, ad groups, and more with optional hierarchical context.

execute_gaql_query

Executes GAQL queries against Google Ads data with options for paging, formatting, and MCC overrides.

get_performance

Retrieves performance metrics at various levels (account, campaign, ad group, etc.) with flexible date ranges and segmentation.

gaql_help

Provides GAQL references and usage guidance for query construction.

refresh_access_token

Refreshes the OAuth access token for an active session when a refresh token is available.