google-ads-mcp

Google Ads MCP Server

This repo contains the source code for running an MCP server that interacts with the Google Ads API.

Tools

The server uses the Google Ads API to provide several Tools and Resources for use with LLMs and AI agents.

Tools available

• search: Retrieves information about the Google Ads account.
• get_resource_metadata: Retrieves metadata about a Google Ads API resource type, for example "campaign". This is useful to understand the structure of the data and what fields are available for querying.
• list_accessible_customers: Returns ids of customers directly accessible by the user authenticating the call.

Configuring and Namespacing Tools

The Google Ads MCP server uses the tools_config.yaml to let you selectively enable or disable individual tools or tool categories (namespaces) and customize their namespace prefixes.

A default tools_config.yaml with all tools enabled is bundled with the package, so the server works out of the box with no extra setup. To customize your installation, the server resolves the configuration in the following order:

1. An explicit path set via the GOOGLE_ADS_MCP_TOOLS_CONFIG environment variable.
2. A tools_config.yaml file in the current working directory.
3. The default tools_config.yaml bundled with the package.

If an explicitly requested configuration file (via the environment variable) is missing, or any resolved file is invalid, the server raises an error and fails to start.

Configuration Example:

namespaces:
  # Option 1: Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Option 2: Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Option 3: Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true

Resources available

• discovery-document: Retrieve the Google Ads API discovery document. Provides the discovery document for the latest version of the Google Ads API, which describes the API surface, including resources, methods, and schemas. Host LLMs should access this resource to understand the structure of the Google Ads API and discover available features.
• metrics: Retrieve information about the metrics available for reporting in the Google Ads API.
• segments: Retrieve information about the segments available for reporting in the Google Ads API.
• release-notes: Retrieve the release notes for the latest version of the Google Ads API.

Notes

1. The MCP Server will expose your data to the Agent or LLM that you connect to it.
2. If you have technical issues, please use the GitHub issue tracker.
3. To help us collect usage data, you will notice an extra header has been added to your API calls: this data is used to improve the product.

Setup instructions

Setup involves the following steps:

1. Configure Python.
2. Configure Developer Token.
3. Enable APIs in your project
4. Configure Credentials.
5. Configure your MCP client.

Configure Python

Install pipx.

After a version has been published to PyPI, you can run that exact version instead of following the latest repository state:

pipx run --spec "google-ads-mcp==X.Y.Z" google-ads-mcp

Configure Developer Token (Optional)

If your setup requires a developer token, follow the instructions for Obtaining a Developer Token.

Your developer token must have at least Explorer access to query production accounts. New tokens may be automatically upgraded to Explorer access; if not, you can apply through the API Center. See the access levels documentation for details.

If you see the error "The developer token is only approved for use with test accounts", your token does not yet have access to production accounts. See the access levels documentation for how to request the access level you need.

Enable APIs in your project

Follow the instructions to enable the following APIs in your Google Cloud project:

• Google Ads API

Configure Credentials

Option 1: Using FastMCP OAuth Proxy

The server supports FastMCP's OAuth proxy feature for dynamic user authentication. This is useful when running the server as a web service.

To enable it, set the following environment variables:

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID: Your Google Cloud OAuth 2.0 Client ID.
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET: Your Google Cloud OAuth 2.0 Client Secret.
• GOOGLE_ADS_MCP_BASE_URL: (Optional) The base URL where the server is accessible (defaults to http://localhost:8080).
• GOOGLE_ADS_MCP_JWT_SIGNING_KEY: (Optional) Secret key used to sign FastMCP JWT tokens across multiple server instances or deployments.
• GOOGLE_ADS_MCP_STORAGE_TYPE: (Optional) Storage backend for OAuth state (filetree, redis, firestore, or memory).
• GOOGLE_ADS_MCP_STORAGE_PATH: (Optional) Directory path for filetree persistent storage.
• GOOGLE_ADS_MCP_STORAGE_REDIS_URL: (Optional) Redis URL for redis persistent storage.
• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT: (Optional) Google Cloud project for firestore persistent storage. Defaults to the project inferred from Application Default Credentials. Setting it selects the firestore backend even if GOOGLE_ADS_MCP_STORAGE_TYPE is unset.
• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE: (Optional) Firestore database name for firestore persistent storage. Defaults to (default).
• GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY: (Optional) Encryption key for stored OAuth tokens.
• GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION: (Optional) Set to true to disable token encryption.

The redis and firestore backends need their storage library installed alongside the server: pip install py-key-value-aio[redis] and pip install google-ads-mcp[firestore] respectively.

Once this is enabled, you can authenticate to the API through your MCP client.

When these variables are set, the server automatically switches to the streamable-http transport (SSE/HTTP) instead of stdio.

You will need to run the server as a separate process and configure your MCP client to connect to the SSE endpoint (e.g., http://localhost:8080/mcp).

Option 2: Configure credentials using Application Default Credentials

Configure your Application Default Credentials (ADC). Make sure the credentials are for a user with access to your Google Ads accounts or properties.

Credentials must include the Google Ads API scope:

https://www.googleapis.com/auth/adwords

Check out Manage OAuth Clients for how to create an OAuth client.

Here are some sample gcloud commands you might find useful:

• Set up ADC using user credentials and an OAuth desktop or web client after downloading the client JSON to YOUR_CLIENT_JSON_FILE.

  bash复制

  gcloud auth application-default login \
    --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
    --client-id-file=YOUR_CLIENT_JSON_FILE

• Set up ADC using service account impersonation.

  bash复制

  gcloud auth application-default login \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

When the gcloud auth application-default command completes, copy the PATH_TO_CREDENTIALS_JSON file location printed to the console in the following message. You will need this for a later step!

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

Option 3: Configure credentials using the Google Ads API Python client library.

Follow the instructions to setup and configure the Google Ads API Python client library

If you have already done this and have a working google-ads.yaml , you can reuse this file!

In the utils.py file, change get_googleads_client() to use the load_from_storage() method.

Configure your MCP client

Add the server to your MCP client's configuration. Below are examples for popular clients.

Antigravity CLI / Antigravity Code Assist

1. Install Antigravity CLI or Antigravity Code Assist.

2. Configure your server. Refer to the docs at https://antigravity.google/docs/mcp for details on setting up MCP servers.

• Option 1: Using FastMCP OAuth Proxy (Streamable HTTP)

  You can run the server as a separate process and configure your MCP client to connect to the SSE endpoint (e.g., http://localhost:8080/mcp). This also allows using FastMCP's OAuth proxy feature for dynamic user authentication.

  json复制

  {
    "mcpServers": {
      "google-ads-mcp": {
        "httpUrl":"http://localhost:8080/mcp",
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"                        
        }
      }
    }
  }

• Option 2: the Application Default Credentials method

  Replace PATH_TO_CREDENTIALS_JSON with the path you copied in the previous step.

  We also recommend that you add a GOOGLE_CLOUD_PROJECT attribute to the env object. Replace YOUR_PROJECT_ID in the following example with the project ID of your Google Cloud project.

  json复制

  {
    "mcpServers": {
      "google-ads-mcp": {
        "command": "pipx",
        "args": [
          "run",
          "--spec",
          "git+https://github.com/googleads/google-ads-mcp.git",
          "google-ads-mcp"
        ],
        "env": {
          "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

• Option 3: the Python client library method

  json复制

  {
    "mcpServers": {
      "google-ads-mcp": {
        "command": "pipx",
        "args": [
          "run",
          "--spec",
          "git+https://github.com/googleads/google-ads-mcp.git",
          "google-ads-mcp"
        ],
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

Login Customer Id

If your access to the customer account is through a manager account, you will need to add the customer ID of the manager account to the settings file.

See here for details.

The final file will look like this:

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",