flin-google-ads-mcp

Read-only MCP server for Google Ads, built for simple public use via uvx.

Why this server

• Read-only by design

• No create/update/delete campaign operations

• Credentials via environment variables only

• Easy local testing with MCP Inspector

Related MCP server: Google Ads MCP Server

Exposed MCP tools

• health_check

• list_accessible_customers

• get_customer_clients

• find_customer_clients

• get_campaigns

• get_ad_groups

• get_ads

• get_insights

• get_keywords

get_ads includes RSA content fields (headlines/descriptions/paths/final URLs) when available.

get_insights supports:

• campaign

• ad_group

• ad

• customer (account-level metrics)

• account (alias of customer)

Requirements

1. Python 3.10+

2. Node.js v25.8.1+ (only for MCP Inspector testing)

3. Google Ads API credentials:

• GOOGLE_ADS_DEVELOPER_TOKEN

• GOOGLE_ADS_CLIENT_ID

• GOOGLE_ADS_CLIENT_SECRET

• GOOGLE_ADS_REFRESH_TOKEN

Optional:

• GOOGLE_ADS_LOGIN_CUSTOMER_ID

• GOOGLE_ADS_CUSTOMER_ID (default customer if no customer_id argument is passed)

• GOOGLE_ADS_USE_PROTO_PLUS (true by default)

For MCC flows, you can also pass login_customer_id directly per tool call.

Quick flow: "Avesco spend yesterday"

1. Find the subaccount by name under the manager:

{
  "tool": "find_customer_clients",
  "args": {
    "manager_customer_id": "6050181535",
    "login_customer_id": "6050181535",
    "name_query": "Avesco",
    "direct_only": false,
    "include_hidden": false,
    "include_self": false,
    "status": "ALL",
    "limit": 50
  }
}

2. Use the returned client_customer_id with account-level insights:

{
  "tool": "get_insights",
  "args": {
    "customer_id": "2054139041",
    "login_customer_id": "6050181535",
    "level": "account",
    "date_range": "YESTERDAY",
    "limit": 10
  }
}

Date ranges

get_insights and get_keywords support:

• TODAY

• YESTERDAY

• THIS_WEEK_MON_TODAY

• THIS_WEEK_SUN_TODAY

• LAST_WEEK_MON_SUN

• LAST_WEEK_SUN_SAT

• LAST_7_DAYS

• LAST_14_DAYS

• LAST_30_DAYS

• LAST_60_DAYS

• LAST_90_DAYS

• THIS_MONTH

• LAST_MONTH

• CUSTOM (requires start_date and end_date in YYYY-MM-DD)

Quickstart (from source)

uv sync --extra dev
cp .env.example .env
# Fill .env values
uv run flin-google-ads-mcp

Quickstart (as published package)

uvx flin-google-ads-mcp@latest

Claude integration (published via uvx)

{
  "mcpServers": {
    "flin-google-ads-mcp": {
      "command": "uvx",
      "args": ["flin-google-ads-mcp@latest"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "xxx",
        "GOOGLE_ADS_CLIENT_ID": "xxx",
        "GOOGLE_ADS_CLIENT_SECRET": "xxx",
        "GOOGLE_ADS_REFRESH_TOKEN": "xxx",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
      }
    }
  }
}

Claude integration (local development)

{
  "mcpServers": {
    "flin-google-ads-mcp-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/nicolasg/Antigravity/flin-google-ads-mcp",
        "flin-google-ads-mcp"
      ],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "xxx",
        "GOOGLE_ADS_CLIENT_ID": "xxx",
        "GOOGLE_ADS_CLIENT_SECRET": "xxx",
        "GOOGLE_ADS_REFRESH_TOKEN": "xxx",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "0987654321"
      }
    }
  }
}

How to test

Detailed guide: docs/testing.md

• Release checklist: docs/release.md

Operational usage guide:

• docs/mcp-usage-guide.md

Fast path:

uv sync --extra dev
python3 -m pytest
python3 -m compileall src

Then run live smoke tests with MCP Inspector (see the testing guide).

Release on GitHub + PyPI

This repository publishes automatically with GitHub Actions:

• CI: .github/workflows/ci.yml

• Release: .github/workflows/release.yml (triggered by git tags v*)

1) Configure PyPI Trusted Publisher (one-time)

In PyPI project settings for flin-google-ads-mcp, add a Trusted Publisher with:

• Owner: flin-agency

• Repository: flin-google-ads-mcp

• Workflow: release.yml

• Environment: pypi

2) Cut a release

# bump version in pyproject.toml first, then:
git add -A
git commit -m "release: v0.1.0"
git tag v0.1.0
git push origin main --tags

The Release workflow builds, tests, and publishes to PyPI using OIDC (no PyPI API token in GitHub secrets).

CI

GitHub Actions validates:

• unit tests

• import/compile checks

• package build