<div align="center">
  <img src="assets/logo.png" alt="Google Ads MCP by AdPlug" width="76" />
  <h1>Google Ads MCP</h1>
  <p><strong>Connect Google Ads to Claude, ChatGPT, Cursor, and any MCP client.</strong><br/>A hosted, remote <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server by <a href="https://adplug.app">AdPlug</a>.</p>

[![Remote MCP server](https://img.shields.io/badge/MCP-remote%20server-b5562e)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-16-2b6cb0)](#tools)
[![Auth](https://img.shields.io/badge/auth-OAuth%202.1-2f855a)](#authentication)
[![Hosted by AdPlug](https://img.shields.io/badge/hosted%20by-AdPlug-1a1a1a)](https://adplug.app)

</div>

> **This is a remote, fully hosted server.** There is nothing to clone, install, or run. Point your MCP client at the endpoint below and sign in. This repository holds the connection setup and documentation only; the server is operated by [AdPlug](https://adplug.app).

## Endpoint

```
https://api.adplug.app/mcp/google-ads
```

## What it does

Manage and analyze Google Ads in plain language from your AI assistant: pull spend and conversion reports across an entire MCC, research keywords, write raw GAQL, and make safe changes with a preview step before anything is committed. Costs come back formatted with currency symbols, account names are always attached to IDs, and MCC parent accounts are auto-detected so you rarely touch `login_customer_id`.

## Built by a PPC veteran

Hi, I'm [Daniel Popa](https://www.linkedin.com/in/danielpopamd), founder of AdPlug. I have spent 10+ years in performance marketing and managed over $100M in ad budgets, running paid acquisition and conversion optimization for brands including Coca-Cola, Rolex, Boots, British Gas, Europcar, O2, and SeedLegals.

I still run Google Ads and LinkedIn Ads every day, and I built this server because I was tired of switching between the AI I think in and the ad platforms I work in. This is not a generic API wrapper. Every tool exists because I needed it on a live account: a cross-account spend overview in one call, conversion reports that handle GAQL segmentation for you, and a preview step before any change touches a real account. If a workflow felt slow in my own day job, it became a tool.

Questions, feature requests, or PPC war stories? Reach me on [LinkedIn](https://www.linkedin.com/in/danielpopamd) or at support@adplug.app.

## Quick start

You need a free [AdPlug](https://adplug.app) account to authorize the connection. The server uses OAuth 2.1: when you add it, your client opens a browser window where you sign in to AdPlug and connect Google Ads. No API keys or tokens are pasted anywhere.

1. Create your account at **[adplug.app](https://adplug.app)** and connect Google Ads.
2. Add the endpoint to your client (pick yours below).
3. Approve the OAuth prompt. You are connected.

## Add it to your client

### Claude.ai and Claude Desktop
Settings → **Connectors** → **Add custom connector** → paste the name and URL:

| Field | Value |
| --- | --- |
| Name | `Google Ads MCP` |
| URL | `https://api.adplug.app/mcp/google-ads` |

A browser window opens to sign in and authorize. Done.

### Claude Code (CLI)
```bash
claude mcp add --transport http adplug-google-ads https://api.adplug.app/mcp/google-ads
```
Then run `/mcp` inside Claude Code and complete the OAuth login.

### ChatGPT
Settings → **Connectors** → **Create** (Developer mode / custom connector) → paste the URL `https://api.adplug.app/mcp/google-ads` and authorize. Requires a ChatGPT plan that supports custom MCP connectors.

### Cursor
[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=adplug-google-ads&config=eyJ1cmwiOiJodHRwczovL2FwaS5hZHBsdWcuYXBwL21jcC9nb29nbGUtYWRzIn0=)

Or add it manually to `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "adplug-google-ads": {
      "url": "https://api.adplug.app/mcp/google-ads"
    }
  }
}
```

### VS Code
```bash
code --add-mcp '{"name":"adplug-google-ads","url":"https://api.adplug.app/mcp/google-ads"}'
```

### Any client that needs a stdio bridge (Windsurf, older desktop apps)
Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge the remote server over stdio. It handles the OAuth handshake for you:
```json
{
  "mcpServers": {
    "adplug-google-ads": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.adplug.app/mcp/google-ads"]
    }
  }
}
```

## Tools

16 tools, designed as a few flexible tools rather than many narrow ones.

| Tool | What it does |
| --- | --- |
| `adplug_get_status` | Check whether Google Ads is connected and healthy. |
| `google_ads_list_accounts` | List all accessible accounts with names, types, currencies, and MCC hierarchy. |
| `google_ads_account_performance` | Cross-account spend overview in one call (skips MCC managers). |
| `google_ads_campaign_performance` | Campaign-level metrics, no GAQL required. |
| `google_ads_conversion_performance` | Conversion-action breakdowns with segmentation handled for you. |
| `google_ads_daily_trends` | Day-by-day metric trends. |
| `google_ads_search_terms` | Search-term report, sorted by cost. |
| `google_ads_shared_set_criteria` | Contents of shared negative-keyword lists. |
| `google_ads_keyword_ideas` | Keyword research and ideas. |
| `google_ads_gaql_doc` | GAQL syntax reference. |
| `google_ads_reporting_view_doc` | Exact field names, types, and filterability for a reporting view. |
| `google_ads_query` | Run raw GAQL for custom or advanced queries. |
| `google_ads_preview_mutation` | Preview a status change (pause / enable / remove) before committing. |
| `google_ads_execute_mutation` | Execute a previewed change. |
| `google_ads_preview_add_negatives` | Preview adding negative keywords (campaign-level or shared list). |
| `google_ads_execute_add_negatives` | Execute the negative-keyword addition. |

## Authentication

OAuth 2.1 with Dynamic Client Registration. Your client discovers the authorization server from the endpoint, registers itself, and opens a browser for you to sign in to AdPlug and grant access. The connection between AdPlug and Google is held server-side and encrypted; the MCP client never sees a Google token.

## Server config (for directory submissions)

```json
{
  "mcpServers": {
    "adplug-google-ads": {
      "url": "https://api.adplug.app/mcp/google-ads"
    }
  }
}
```

## Links

- Website: https://adplug.app
- Dashboard and connections: https://adplug.app/dashboard/connections
- Setup guide: https://adplug.app/guides/google-ads
- Support: support@adplug.app

## More from AdPlug

[AdPlug](https://adplug.app) is a marketing control plane that plugs your ad accounts into AI assistants over the Model Context Protocol. This is one of several AdPlug servers:

- **Google Ads MCP** (this one): `https://api.adplug.app/mcp/google-ads`
- **LinkedIn Ads MCP**: `https://api.adplug.app/mcp/linkedin-ads`
- **Unified** (Google Ads and LinkedIn Ads in one connector): `https://api.adplug.app/mcp`

One AdPlug account works across all of them.

## License

[MIT](LICENSE) for the contents of this repository (setup and documentation). The hosted service has its own [terms](https://adplug.app).

> Google Ads is a trademark of Google LLC. AdPlug is an independent integration and is not endorsed by or affiliated with Google.