diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 7eb2de2f..e19d3302 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -332,6 +332,11 @@ "name": "x-ads", "source": "third_party/x-ads", "description": "Manage ad campaigns, create ads, track conversions, and pull performance stats." + }, + { + "name": "google-ads", + "source": "third_party/google-ads", + "description": "Query ad accounts, campaigns, and performance reports with GAQL." } ] } diff --git a/README.md b/README.md index 5408d433..fdb8d546 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc | `similarweb` | [Similarweb](third_party/similarweb/) | Cursor | Integrations | Analyze website traffic, audiences, and competitors. | | `xero` | [Xero](third_party/xero/) | Cursor | Integrations | Read and write invoices, contacts, reports, and payroll. | | `x-ads` | [X Ads](third_party/x-ads/) | Cursor | Integrations | Manage ad campaigns, create ads, track conversions, and pull performance stats. | +| `google-ads` | [Google Ads](third_party/google-ads/) | Cursor | Integrations | Query ad accounts, campaigns, and performance reports with GAQL. | Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest). ## Repository structure diff --git a/third_party/google-ads/.cursor-plugin/plugin.json b/third_party/google-ads/.cursor-plugin/plugin.json new file mode 100644 index 00000000..1e69e23f --- /dev/null +++ b/third_party/google-ads/.cursor-plugin/plugin.json @@ -0,0 +1,61 @@ +{ + "name": "google-ads", + "displayName": "Google Ads", + "version": "1.0.0", + "minClientVersions": { + "cursor": "3.13.0" + }, + "description": "Query ad accounts, campaigns, and performance reports with GAQL.", + "author": { + "name": "Cursor", + "email": "plugins@cursor.com" + }, + "homepage": "https://github.com/googleads/google-ads-mcp", + "repository": "https://github.com/cursor/plugins", + "license": "MIT", + "logo": "assets/logo.svg", + "keywords": [ + "google", + "google-ads", + "ads", + "advertising", + "campaigns", + "gaql", + "reporting", + "analytics", + "mcp" + ], + "category": "integrations", + "tags": [ + "google", + "ads", + "advertising", + "mcp" + ], + "variables": { + "type": "object", + "properties": { + "GOOGLE_ADS_DEVELOPER_TOKEN": { + "type": "string", + "title": "Google Ads developer token", + "description": "Developer token from the API Center of your Google Ads manager account. Needs at least Explorer access to query production accounts." + }, + "GOOGLE_APPLICATION_CREDENTIALS": { + "type": "string", + "title": "Application Default Credentials file", + "description": "Absolute path to the credentials JSON written by `gcloud auth application-default login`. The login must include the https://www.googleapis.com/auth/adwords scope." + }, + "GOOGLE_PROJECT_ID": { + "type": "string", + "title": "Google Cloud project ID", + "description": "ID of the Google Cloud project where the Google Ads API is enabled and your OAuth client was created." + } + }, + "required": [ + "GOOGLE_ADS_DEVELOPER_TOKEN", + "GOOGLE_APPLICATION_CREDENTIALS", + "GOOGLE_PROJECT_ID" + ] + }, + "mcpServers": "./mcp.json" +} diff --git a/third_party/google-ads/CHANGELOG.md b/third_party/google-ads/CHANGELOG.md new file mode 100644 index 00000000..927ed22f --- /dev/null +++ b/third_party/google-ads/CHANGELOG.md @@ -0,0 +1,10 @@ +# Changelog + +All notable changes to this plugin will be documented here. + +## 1.0.0 — initial release + +- Added the `google-ads` MCP server running Google's official `google-ads-mcp` locally via `pipx run --spec git+https://github.com/googleads/google-ads-mcp.git`, the configuration Google documents for MCP clients. +- Configuration variables for the Google Ads API developer token, the Application Default Credentials file (authorized with the `https://www.googleapis.com/auth/adwords` scope), and the Google Cloud project ID. No client ID, secret, or token is bundled. +- Separate from the Gmail, Google Drive, and Google Calendar plugins: Google does not host a Google Ads MCP endpoint, and the Ads API needs its own developer token and OAuth scope rather than a Workspace sign-in. +- Logo: official Google Ads product icon on a padded white tile. diff --git a/third_party/google-ads/LICENSE b/third_party/google-ads/LICENSE new file mode 100644 index 00000000..ca2bba77 --- /dev/null +++ b/third_party/google-ads/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Cursor + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/third_party/google-ads/README.md b/third_party/google-ads/README.md new file mode 100644 index 00000000..0d3f7b31 --- /dev/null +++ b/third_party/google-ads/README.md @@ -0,0 +1,126 @@ +# Google Ads + +Cursor plugin that connects agents to the [Google Ads API](https://developers.google.com/google-ads/api) through Google's official [Google Ads MCP server](https://github.com/googleads/google-ads-mcp), run locally by Cursor. + +List the customer accounts you can access, run [GAQL](https://developers.google.com/google-ads/api/docs/query/overview) reports over campaigns, ad groups, keywords, and metrics, and inspect the API's resource metadata. The official server is read-only: it can query and report, but it does not create or change campaigns, bids, or budgets. + +## Install + +1. Open **Cursor Settings → Plugins**. +2. Search for **Google Ads**. +3. Click **Install**, then set the developer token, credentials path, and project ID (see [Before you connect](#before-you-connect)). + +Or run `/add-plugin google-ads` in chat. + +## MCP + +```json +{ + "mcpServers": { + "google-ads": { + "type": "stdio", + "command": "pipx", + "args": [ + "run", + "--spec", + "git+https://github.com/googleads/google-ads-mcp.git", + "google-ads-mcp" + ], + "env": { + "GOOGLE_APPLICATION_CREDENTIALS": "${GOOGLE_APPLICATION_CREDENTIALS}", + "GOOGLE_PROJECT_ID": "${GOOGLE_PROJECT_ID}", + "GOOGLE_ADS_DEVELOPER_TOKEN": "${GOOGLE_ADS_DEVELOPER_TOKEN}" + } + } + } +} +``` + +This is the same `pipx run` configuration that Google documents in the [developer integration guide](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server). Google does not publish a hosted MCP endpoint for Google Ads, so the server runs on your machine over stdio. + +## This is not a Google Workspace sign-in + +The [Gmail](../gmail/), [Google Drive](../google-drive/), and [Google Calendar](../google-calendar/) plugins point at Google-hosted MCP endpoints, and Cursor prompts for a Google sign-in when they connect. Google Ads works differently, and a Workspace sign-in from those plugins does not carry over: + +- **You need a Google Ads API developer token.** Every request carries a developer token issued through the API Center of a Google Ads manager account. Tokens start with test-account-only access; querying production accounts needs at least [Explorer access](https://developers.google.com/google-ads/api/docs/get-started/dev-token#access-levels). +- **You need Ads-specific OAuth scopes.** The Google Ads API requires the `https://www.googleapis.com/auth/adwords` scope. Workspace tokens do not include it, so you authorize separately with your own OAuth client, in a Google Cloud project where the Google Ads API is enabled. +- **Credentials live on your machine.** The server reads [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) from the file you point `GOOGLE_APPLICATION_CREDENTIALS` at. There is no browser sign-in inside Cursor for this plugin. + +If you prefer a browser sign-in, the official server also supports a FastMCP OAuth proxy when you [self-host it on Cloud Run](https://github.com/googleads/google-ads-mcp#deployment-to-google-cloud-platform) with your own OAuth client ID and secret. Point the plugin's `mcp.json` at that deployment instead: + +```json +{ + "mcpServers": { + "google-ads": { + "type": "http", + "url": "https://YOUR-CLOUD-RUN-URL.a.run.app/mcp" + } + } +} +``` + +## Before you connect + +1. **Install [pipx](https://pipx.pypa.io/stable/#install-pipx).** Cursor launches the server with `pipx run`, which downloads it from GitHub on first use. Python 3.10 or newer is required. +2. **Get a developer token.** Follow [Obtaining a developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token). If you see *"The developer token is only approved for use with test accounts"*, request a higher [access level](https://developers.google.com/google-ads/api/docs/access-levels) in the API Center. +3. **Enable the Google Ads API** in a Google Cloud project: [Google Ads API library page](https://console.cloud.google.com/apis/library/googleads.googleapis.com). +4. **Create an OAuth client** (Desktop or Web) in that project and download its client JSON. See [Manage OAuth clients](https://support.google.com/cloud/answer/15549257). +5. **Sign in with the Ads scope** as a user who can access your Google Ads accounts: + + ```shell + gcloud auth application-default login \ + --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \ + --client-id-file=YOUR_CLIENT_JSON_FILE + ``` + + Copy the path printed as `Credentials saved to file: [...]`. +6. **Configure the plugin** in **Dashboard → Plugins → Configure**: the developer token, the credentials path from step 5, and the project ID from step 3. + +### Manager accounts + +If you reach the customer accounts through a manager (MCC) account, the server also needs the manager's customer ID. Add it to the server's `env`: + +```json +"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890" +``` + +See [login customer ID](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) for details. + +## What agents can do + +| Tool | What it does | +| --- | --- | +| `list_accessible_customers` | Customer IDs directly accessible to the signed-in user | +| `search` | Run a GAQL query against a customer account: campaigns, ad groups, ads, keywords, metrics, segments | +| `get_resource_metadata` | Fields and structure of a Google Ads API resource type, such as `campaign` | + +| Resource | What it provides | +| --- | --- | +| `discovery-document` | Discovery document for the latest Google Ads API version | +| `metrics` | Metrics available for reporting | +| `segments` | Segments available for reporting | +| `release-notes` | Release notes for the latest API version | + +Most prompts need a customer ID; including it in the prompt (`How many active campaigns for customer id 1234567890?`) saves a round trip. Individual tools and namespaces can be enabled, disabled, or prefixed with a `tools_config.yaml` — see the [server README](https://github.com/googleads/google-ads-mcp#configuring-and-namespacing-tools). + +## Notes + +- This is a local stdio server, so `pipx` and Python 3.10+ have to be available on the machine running Cursor. +- The server exposes your Google Ads data to the agent you connect it to, and adds a usage header to its API calls that Google uses to improve the product. +- Requests run as the user who signed in with `gcloud` and are subject to that user's Google Ads access and the developer token's access level. +- Credentials and tokens are yours: this plugin ships no client ID, client secret, or developer token. + +## Docs + +- Google Ads MCP server: https://github.com/googleads/google-ads-mcp +- Developer integration guide: https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server +- Developer token: https://developers.google.com/google-ads/api/docs/get-started/dev-token +- Access levels: https://developers.google.com/google-ads/api/docs/access-levels +- GAQL: https://developers.google.com/google-ads/api/docs/query/overview + +Logo is the official Google Ads product icon, placed on a white tile with padding so it reads well in the Cursor UI: +https://www.gstatic.com/images/branding/productlogos/ads/v5/192px.svg + +## License + +MIT diff --git a/third_party/google-ads/assets/logo.svg b/third_party/google-ads/assets/logo.svg new file mode 100644 index 00000000..d737af12 --- /dev/null +++ b/third_party/google-ads/assets/logo.svg @@ -0,0 +1 @@ + diff --git a/third_party/google-ads/mcp.json b/third_party/google-ads/mcp.json new file mode 100644 index 00000000..1c022820 --- /dev/null +++ b/third_party/google-ads/mcp.json @@ -0,0 +1,19 @@ +{ + "mcpServers": { + "google-ads": { + "type": "stdio", + "command": "pipx", + "args": [ + "run", + "--spec", + "git+https://github.com/googleads/google-ads-mcp.git", + "google-ads-mcp" + ], + "env": { + "GOOGLE_APPLICATION_CREDENTIALS": "${GOOGLE_APPLICATION_CREDENTIALS}", + "GOOGLE_PROJECT_ID": "${GOOGLE_PROJECT_ID}", + "GOOGLE_ADS_DEVELOPER_TOKEN": "${GOOGLE_ADS_DEVELOPER_TOKEN}" + } + } + } +}