Spark
Sign In
MCP Connector

Integrate Google Ads API for Data Access

A FastMCP-powered Google Ads MCP server with automatic OAuth 2.0, GAQL query execution, and keyword research tools.

Connect
Works with google adsgithub
VibeBaza
Own this? Claim it

Maintainer of this project? Claim this page to edit the listing.

90
Spark score
out of 100
Updated 7 months ago
Fresher alternatives ↓
Version 1.0.0
Models
universal
Add to Favorites

Why it matters

Connect to the Google Ads API to automate data retrieval and keyword research. This asset enables GAQL queries and provides insights for campaign optimization.

Outcomes

What it gets done

01

Execute GAQL queries for campaign performance analysis.

02

Perform keyword research with search volume data.

03

List and manage Google Ads accounts.

04

Automate OAuth 2.0 authentication and token refresh.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/vb-google-ads | bash

Capabilities

Tools your agent gets

list_accounts

Get a list of all available Google Ads accounts

run_gaql

Execute GAQL queries with custom formatting

run_keyword_planner

Generate keyword ideas with metrics

Overview

Google Ads MCP Server

A FastMCP-powered Google Ads MCP server with automatic OAuth 2.0 authentication, exposing GAQL query execution, account listing, and keyword research tools. Use it when Claude needs to query Google Ads campaign data, run custom GAQL reports, or research keywords directly.

What it does

This FastMCP-powered Model Context Protocol server integrates with the Google Ads API, handling automatic OAuth 2.0 authentication and exposing GAQL (Google Ads Query Language) queries and keyword research. It provides three tools: list_accounts (retrieve every Google Ads account you have access to), run_gaql (execute custom GAQL queries with formatted output), and run_keyword_planner (generate keyword ideas with search-volume and other metrics).

Authentication is handled automatically with a one-time browser-based OAuth setup and smart token management that refreshes tokens without manual intervention, with tokens stored securely on the local machine. The server can run in standard stdio mode for Claude Desktop or in HTTP mode for remote access.

git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -r requirements.txt

When to use - and when NOT to

Use this connector when Claude needs to query Google Ads data directly - listing accessible accounts, running custom GAQL queries for campaign performance or conversion data, or generating keyword ideas with search metrics for a given topic.

It is not a fit without an approved Google Ads API developer token and a Google Cloud Platform project with OAuth 2.0 credentials configured - both are required before the server can authenticate against the Google Ads API.

Capabilities

list_accounts retrieves all accessible Google Ads accounts; run_gaql executes custom Google Ads Query Language queries with formatted results; run_keyword_planner generates keyword ideas with search-query metrics. Built on the FastMCP framework with automatic OAuth 2.0 token refresh and secure local token storage.

How to install

Install from source with the commands above, then start the server directly (stdio mode) or with python3 server.py --http for HTTP mode. For Claude Desktop, point the MCP config at your virtual environment's Python interpreter and the server script; for HTTP mode, point it at http://127.0.0.1:8000/mcp. Two environment variables are required: GOOGLE_ADS_DEVELOPER_TOKEN (your Google Ads API developer token) and GOOGLE_ADS_OAUTH_CONFIG_PATH (path to the OAuth credentials JSON file downloaded from Google Cloud). GOOGLE_ADS_LOGIN_CUSTOMER_ID is optional, for managing multiple accounts under an MCC manager account. A one-click installer is also available at gomarble.ai/mcp.

Who it's for

Marketers and analysts who want Claude to query Google Ads campaign performance, run custom GAQL reports, and research keywords directly, with a Google Cloud Platform project, a Google Ads account with API access, and an approved developer token already in place.

Source README

FastMCP-powered Model Context Protocol server for integrating with Google Ads API featuring automatic OAuth 2.0 authentication, enabling GAQL query execution and keyword research.

Installation

From Source

### Clone the repository
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

### Create virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

### Install dependencies
pip install -r requirements.txt

HTTP Mode

### Start server in HTTP mode
python3 server.py --http

Configuration

Claude Desktop

{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

HTTP Mode Configuration

{
  "mcpServers": {
    "google-ads": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Available Tools

Tool Description
list_accounts Retrieve a list of all available Google Ads accounts
run_gaql Execute GAQL queries with custom formatting
run_keyword_planner Generate keyword ideas with metrics

Features

  • Automatic OAuth 2.0 authentication with one-time browser setup
  • Smart token management with automatic refresh
  • Execute GAQL (Google Ads Query Language) queries
  • Account management and listing
  • Keyword research with search volume data
  • Built on the FastMCP framework
  • Ready-to-use Claude Desktop integration
  • Secure local token storage

Environment Variables

Required

  • GOOGLE_ADS_DEVELOPER_TOKEN - Google Ads API Developer token
  • GOOGLE_ADS_OAUTH_CONFIG_PATH - Path to the OAuth credentials JSON file downloaded from Google Cloud

Optional

  • GOOGLE_ADS_LOGIN_CUSTOMER_ID - Manager account configuration for managing multiple accounts under MCC

Usage Examples

List all my Google Ads accounts

Show me campaign performance for account 1234567890 in the last 30 days

Generate keyword ideas for 'digital marketing' using account 1234567890

Get conversion data for all campaigns in the last week

Which campaigns have the highest cost per conversion?

Resources

Notes

Requires a Google Cloud Platform account, a Google Ads account with API access, and an approved developer token. Includes comprehensive guidance for setting up OAuth 2.0 credentials and configuring the Google Ads API. One-click installer available at https://gomarble.ai/mcp

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.