Google Ads MCP Server (Experimental)

This repo contains the source code for running a localMCP server that interacts with theGoogle Ads API.

Tools

The server uses theGoogle Ads APIto provide severalTools for use with LLMs.

Tools available

search: Retrieves information about the Google Ads account.
list_accessible_customers: Returns names of customers directly accessibleby the user authenticating the call.

Notes

The MCP Server will expose your data to the Agent or LLM that you connect to it.
If you have technical isses, please use the GitHub issue tracker.
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:

Configure Python.
Configure Developer Token.
Enable APIs in your project
Configure Credentials.
Configure Gemini.

Configure Python

Install pipx.

Configure Developer Token

Follow the instructions for Obtaining a Developer Token.

Record 'YOUR_DEVELOPER_TOKEN', you will need this for the the 'Configure Gemini' step below

Enable APIs in your project

Follow the instructionsto enable the following APIs in your Google Cloud project:

Google Ads API

Configure Credentials

Option 1: 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 Adsaccounts or properties.

Credentials must include the Google Ads API scope:

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

Check outManage OAuth Clientsfor 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 afterdownloading the client JSON to YOUR_CLIENT_JSON_FILE.

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.

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 thePATH_TO_CREDENTIALS_JSON file location printed to the console in thefollowing message. You will need this for a later step!

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

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

Follow the instructionsto 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 Gemini

Install GeminiCLIor Gemini CodeAssist
Create or edit the file at ~/.gemini/settings.json, adding your serverto the mcpServers list.

Option 1: the Application Default Credentials method

Replace PATH_TO_CREDENTIALS_JSON with the path you copied in the previousstep.

We also recommend that you add a GOOGLE_CLOUD_PROJECT attribute to theenv object. Replace YOUR_PROJECT_ID in the following example with theproject ID of yourGoogle Cloud project.

{
  "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 2: the Python client library method

{
  "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 willneed 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",
        "--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",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}

Subject Delegation (Service Accounts Only)

If you're using service account credentials and need to impersonate a specific user, you can add the GOOGLE_ADS_SUBJECT environment variable with the email address of the user to impersonate.

Important Notes:

This feature only works with service account credentials. If you're using OAuth credentials (Option 1 with user credentials), the subject parameter will be logged but ignored.
The service account must have domain-wide delegation enabled and the appropriate scopes granted by a workspace administrator.

See Domain-wide delegation for more details.

Example configuration with subject delegation:

{
  "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_SERVICE_ACCOUNT_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_SUBJECT": "[email protected]"
      }
    }
  }
}

Try it out

Launch Gemini Code Assist or Gemini CLI and type /mcp. You should seegoogle-ads-mcp listed in the results.

Here are some sample prompts to get you started:

Ask what the server can do:
```
what can the ads-mcp server do?
```
Ask about customers:
```
what customers do I have access to?
```

Ask about campaigns

How many active campaigns do I have?

How is my campaign performance this week?

Note about Customer ID

Your agent will need and ask for a customer id for most prompts. If you aremoving between multiple customers, including the customer ID in the prompt maybe simpler.

How many active campaigns do I have for customer id 1234567890

Contributing

Contributions welcome! See the Contributing Guide.

Credits

This project is based on Google Ads MCPby Google LLC, licensed under the Apache License 2.0.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Google Ads MCP Server (Experimental)