Self-hosted setup

Prerequisites

A Google Ads account
Google Ads API credentials (developer token, OAuth client ID/secret, refresh token)

Install

Option 1: pip (recommended)

Requires Python 3.11+.

pip install burnr8

Option 2: Docker

No Python required. Pull from Docker Hub or GitHub Container Registry:

# Docker Hub
docker pull harrisonhesslink/burnr8

# Or GitHub Container Registry
docker pull ghcr.io/harrisonhesslink/burnr8

Option 3: Clone the repo

Needed if you want to run the OAuth setup script or contribute:

git clone https://github.com/harrisonhesslink/burnr8
cd burnr8
pip install -e .

Get Google Ads credentials

You need four things from the Google Ads API console:

Developer token from your Google Ads manager account
OAuth client ID from Google Cloud Console
OAuth client secret from Google Cloud Console
Refresh token generated via the setup script (see below)

Generate a refresh token

This script is only available if you cloned the repo (not via pip install):

python setup_oauth.py

This opens a browser window. Sign in with the Google account that has access to your Google Ads accounts. The script outputs your refresh token.

Configure

Create a .env file in the directory where you run burn-r8. The server loads it automatically via dotenv:

GOOGLE_ADS_DEVELOPER_TOKEN=your-developer-token
GOOGLE_ADS_CLIENT_ID=your-client-id
GOOGLE_ADS_CLIENT_SECRET=your-client-secret
GOOGLE_ADS_REFRESH_TOKEN=your-refresh-token
# Optional: only needed for MCC (manager) accounts. Dashes are auto-stripped.
# GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890

Connect to your MCP client

Claude Code

Add to ~/.claude/.mcp.json (note the dot before mcp):

{
  "mcpServers": {
    "burnr8": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "burnr8.server"]
    }
  }
}

Or use the CLI:

claude mcp add --scope user --transport stdio burnr8 -- python -m burnr8.server

Your credentials are loaded from the .env file automatically. No need to duplicate them in the MCP config.

Claude Code with Docker

{
  "mcpServers": {
    "burnr8": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/your/.env",
        "harrisonhesslink/burnr8"
      ]
    }
  }
}

Replace /path/to/your/.env with the path to your credentials file.

Claude Desktop

Open Settings, go to Developer, click Edit Config, and add:

{
  "mcpServers": {
    "burnr8": {
      "command": "python",
      "args": ["-m", "burnr8.server"]
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "burnr8": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/your/.env",
        "harrisonhesslink/burnr8"
      ]
    }
  }
}

Cursor

Add the same stdio configuration in Cursor's MCP settings.

Verify

Open your MCP client and try:

List my Google Ads accounts

You should see your accessible customer IDs. Then try:

Run a quick audit on account 1234567890

Note: customer IDs passed to tools should be without dashes (e.g. 1234567890, not 123-456-7890).