diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index a43116e9..c091c153 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -322,6 +322,11 @@ "name": "onedrive", "source": "third_party/onedrive", "description": "Browse, search, and read Microsoft OneDrive files." + }, + { + "name": "x-ads", + "source": "third_party/x-ads", + "description": "Manage ad campaigns, create ads, track conversions, and pull performance stats." } ] } diff --git a/README.md b/README.md index bbe4867f..62440cd7 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc | `readwise` | [Readwise](third_party/readwise/) | Cursor | Integrations | Search highlights and Reader documents, save articles. | | `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. | 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/x-ads/.cursor-plugin/plugin.json b/third_party/x-ads/.cursor-plugin/plugin.json new file mode 100644 index 00000000..08cb49e3 --- /dev/null +++ b/third_party/x-ads/.cursor-plugin/plugin.json @@ -0,0 +1,35 @@ +{ + "name": "x-ads", + "displayName": "X Ads", + "version": "1.0.0", + "minClientVersions": { + "cursor": "3.13.0" + }, + "description": "Manage ad campaigns, create ads, track conversions, and pull performance stats.", + "author": { + "name": "Cursor", + "email": "plugins@cursor.com" + }, + "homepage": "https://docs.x.com/x-ads-api/introduction", + "repository": "https://github.com/cursor/plugins", + "license": "MIT", + "logo": "assets/logo.png", + "keywords": [ + "x", + "twitter", + "ads", + "advertising", + "campaigns", + "conversions", + "analytics", + "mcp" + ], + "category": "integrations", + "tags": [ + "x", + "ads", + "advertising", + "mcp" + ], + "mcpServers": "./mcp.json" +} diff --git a/third_party/x-ads/CHANGELOG.md b/third_party/x-ads/CHANGELOG.md new file mode 100644 index 00000000..70b7cd81 --- /dev/null +++ b/third_party/x-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 `x-ads` MCP server pointing at `https://ads-api.x.com/mcp`. +- OAuth user sign-in using X's client ID `NGdZYmo4VVp2T1BnRG55NlExOGQ6MTpjaQ` (the same client the X connector uses), requesting `ads.read`, `ads.write`, `media.write`, and `offline.access`. +- Separate plugin from X: `ads-api.x.com` is a different protected resource than `api.x.com` with different scopes, so it requires its own authorization. +- Logo: X's official mark from the X brand toolkit, on a black tile matching X's own app icon. diff --git a/third_party/x-ads/LICENSE b/third_party/x-ads/LICENSE new file mode 100644 index 00000000..ca2bba77 --- /dev/null +++ b/third_party/x-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/x-ads/README.md b/third_party/x-ads/README.md new file mode 100644 index 00000000..44e9aab1 --- /dev/null +++ b/third_party/x-ads/README.md @@ -0,0 +1,70 @@ +# X Ads + +Cursor plugin that connects agents to the [X Ads API](https://docs.x.com/x-ads-api/introduction) through X's official hosted [Model Context Protocol](https://modelcontextprotocol.io/) server at `https://ads-api.x.com/mcp`. + +This plugin signs you in with OAuth as your own X account and works with the ads accounts you can access. Agents can manage campaigns, create ads, set up pixels and conversion tracking, and pull performance stats. + +This is a separate plugin from the [X](../x/) plugin: the ads MCP server lives on a different subdomain (`ads-api.x.com` vs `api.x.com`) and requires different OAuth scopes, so it needs its own authorization. Installing both means signing in twice — once per plugin. + +## Install + +1. Open **Cursor Settings → Plugins**. +2. Search for **X Ads**. +3. Click **Install**, then complete the OAuth sign-in when prompted. + +Or run `/add-plugin x-ads` in chat. + +## MCP + +```json +{ + "mcpServers": { + "x-ads": { + "type": "http", + "url": "https://ads-api.x.com/mcp", + "auth": { + "CLIENT_ID": "NGdZYmo4VVp2T1BnRG55NlExOGQ6MTpjaQ", + "scopes": [ + "ads.read", + "ads.write", + "media.write", + "offline.access" + ] + } + } + } +} +``` + +## What agents can do + +| Category | Capabilities | +| --- | --- | +| Accounts | Read your ads accounts, funding instruments, and settings | +| Campaigns | Create, update, pause, and read campaigns and line items | +| Ads & creatives | Create and manage promoted ads and creatives | +| Audiences | Read and manage targeting and audiences | +| Pixels & conversions | Set up the X pixel and conversion tracking | +| Analytics | Pull campaign, line item, and ad performance stats | + +## Setup + +No token to paste — the plugin ships with X's OAuth client ID (the same one the X connector uses) and requests the scopes below. On first use, Cursor opens a browser window where you sign in to X and approve access. The `offline.access` scope lets Cursor refresh the session automatically, so you only sign in once. + +Requests run in your user context against the ads accounts your X account can access. You can revoke access at any time from your X account's connected apps settings. + +## Scopes requested + +`ads.read`, `ads.write`, `media.write`, `offline.access` + +## Docs + +- X Ads API: https://docs.x.com/x-ads-api/introduction +- OAuth protected resource metadata: https://ads-api.x.com/.well-known/oauth-protected-resource +- Authentication overview: https://docs.x.com/fundamentals/authentication/overview + +Logo is X's official mark from the [X brand toolkit](https://about.x.com/en/who-we-are/brand-toolkit), placed on a black tile matching X's own app icon. + +## License + +MIT diff --git a/third_party/x-ads/assets/logo.png b/third_party/x-ads/assets/logo.png new file mode 100644 index 00000000..b3170753 Binary files /dev/null and b/third_party/x-ads/assets/logo.png differ diff --git a/third_party/x-ads/mcp.json b/third_party/x-ads/mcp.json new file mode 100644 index 00000000..a0f9afce --- /dev/null +++ b/third_party/x-ads/mcp.json @@ -0,0 +1,17 @@ +{ + "mcpServers": { + "x-ads": { + "type": "http", + "url": "https://ads-api.x.com/mcp", + "auth": { + "CLIENT_ID": "NGdZYmo4VVp2T1BnRG55NlExOGQ6MTpjaQ", + "scopes": [ + "ads.read", + "ads.write", + "media.write", + "offline.access" + ] + } + } + } +}