flin-google-ads-mcp 0.1.0

Read-only MCP server for Google Ads entities and reporting.

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

Exposed MCP tools

• health_check
• list_accessible_customers
• get_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.

Requirements

1. Python 3.10+
2. Node.js (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.

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": "6050181535",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "3943585717"
      }
    }
  }
}

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