Google Ads MCP Server

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

Tools

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

Tools available

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

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 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 instructions to 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 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.

  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 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 2: 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 Gemini

1. Install Gemini CLI or Gemini Code Assist

2. Create or edit the file at ~/.gemini/settings.json, adding your server to the mcpServers list.

• Option 1: 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.

  {
    "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 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",
        "--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"
      }
    }
  }
}

Try it out

Launch Gemini Code Assist or Gemini CLI and type /mcp. You should see google-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 are moving between multiple customers, including the customer ID in the prompt may be simpler.

How many active campaigns do I have for customer id 1234567890

Authentication Setup (WorkOS AuthKit)

The MCP server supports optional user authentication via WorkOS AuthKit as an OAuth 2.1 Authorization Server. When enabled, every MCP request must include a valid JWT in the Authorization: Bearer <token> header.

Authentication is opt-in: if the environment variables below are not set, the server starts without auth (backward compatible).

WorkOS Dashboard Configuration

1. Create a WorkOS account and note your AuthKit subdomain (e.g. adviso.authkit.app).
2. Enable CIMD: Dashboard → Connect → Configuration → Enable Client ID Metadata Document. This lets MCP clients (VS Code, Claude Desktop) identify themselves without prior registration.
3. Enable Google provider: Dashboard → Authentication → Social Login → Google. You will need Google Cloud OAuth credentials.
4. (Optional) Enable DCR (Dynamic Client Registration) for clients that don't support CIMD.

Environment Variables

Variable	Description	Example
WORKOS_AUTHKIT_ISSUER_URL	AuthKit issuer URL	https://adviso.authkit.app
GOOGLE_ADS_MCP_SERVER_URL	Public URL of this MCP server (for RFC 9728 resource metadata)	https://mcp.example.com
ENCRYPTION_KEY	AES-256-GCM key for encrypting credentials at rest (32 bytes, base64-encoded). Required.	See below

WORKOS_AUTHKIT_ISSUER_URL and GOOGLE_ADS_MCP_SERVER_URL must both be set to activate authentication. ENCRYPTION_KEY is always required — the server refuses to start without it.

Generate a key:

python -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

Multi-user storage

The server stores OAuth credentials in a SQLite database (credentials.db) located in GOOGLE_ADS_MCP_DATA_DIR (default ~/.google_ads_mcp/). Each WorkOS user (identified by the JWT sub claim) has their own encrypted credential entry. Tokens are encrypted at rest using AES-256-GCM.

Verifying Authentication

Once configured, the server exposes GET /.well-known/oauth-protected-resource returning the resource metadata (RFC 9728). Clients that support MCP auth will automatically discover the WorkOS authorization server and initiate the OAuth flow.

Contributing

Contributions welcome! See the Contributing Guide.