Skip to content

Commit 82f1d4f

Browse files
maloneyamaloneya
authored
Merge pull request #302 from nathanl-web/x-ads-plugin
Add X Ads third-party MCP plugin
2 parents 23a56e2 + 164c539 commit 82f1d4f

8 files changed

Lines changed: 159 additions & 0 deletions

File tree

‎.cursor-plugin/marketplace.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,11 @@
322322
"name": "onedrive",
323323
"source": "third_party/onedrive",
324324
"description": "Browse, search, and read Microsoft OneDrive files."
325+
},
326+
{
327+
"name": "x-ads",
328+
"source": "third_party/x-ads",
329+
"description": "Manage ad campaigns, create ads, track conversions, and pull performance stats."
325330
}
326331
]
327332
}

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc
6666
| `readwise` | [Readwise](third_party/readwise/) | Cursor | Integrations | Search highlights and Reader documents, save articles. |
6767
| `similarweb` | [Similarweb](third_party/similarweb/) | Cursor | Integrations | Analyze website traffic, audiences, and competitors. |
6868
| `xero` | [Xero](third_party/xero/) | Cursor | Integrations | Read and write invoices, contacts, reports, and payroll. |
69+
| `x-ads` | [X Ads](third_party/x-ads/) | Cursor | Integrations | Manage ad campaigns, create ads, track conversions, and pull performance stats. |
6970
Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest).
7071

7172
## Repository structure

‎third_party/x-ads/.cursor-plugin/plugin.json‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{
2+
"name": "x-ads",
3+
"displayName": "X Ads",
4+
"version": "1.0.0",
5+
"minClientVersions": {
6+
"cursor": "3.13.0"
7+
},
8+
"description": "Manage ad campaigns, create ads, track conversions, and pull performance stats.",
9+
"author": {
10+
"name": "Cursor",
11+
"email": "plugins@cursor.com"
12+
},
13+
"homepage": "https://docs.x.com/x-ads-api/introduction",
14+
"repository": "https://github.com/cursor/plugins",
15+
"license": "MIT",
16+
"logo": "assets/logo.png",
17+
"keywords": [
18+
"x",
19+
"twitter",
20+
"ads",
21+
"advertising",
22+
"campaigns",
23+
"conversions",
24+
"analytics",
25+
"mcp"
26+
],
27+
"category": "integrations",
28+
"tags": [
29+
"x",
30+
"ads",
31+
"advertising",
32+
"mcp"
33+
],
34+
"mcpServers": "./mcp.json"
35+
}

‎third_party/x-ads/CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Changelog
2+
3+
All notable changes to this plugin will be documented here.
4+
5+
## 1.0.0 — initial release
6+
7+
- Added the `x-ads` MCP server pointing at `https://ads-api.x.com/mcp`.
8+
- 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`.
9+
- 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.
10+
- Logo: X's official mark from the X brand toolkit, on a black tile matching X's own app icon.

‎third_party/x-ads/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Cursor
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎third_party/x-ads/README.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# X Ads
2+
3+
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`.
4+
5+
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.
6+
7+
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.
8+
9+
## Install
10+
11+
1. Open **Cursor Settings → Plugins**.
12+
2. Search for **X Ads**.
13+
3. Click **Install**, then complete the OAuth sign-in when prompted.
14+
15+
Or run `/add-plugin x-ads` in chat.
16+
17+
## MCP
18+
19+
```json
20+
{
21+
"mcpServers": {
22+
"x-ads": {
23+
"type": "http",
24+
"url": "https://ads-api.x.com/mcp",
25+
"auth": {
26+
"CLIENT_ID": "NGdZYmo4VVp2T1BnRG55NlExOGQ6MTpjaQ",
27+
"scopes": [
28+
"ads.read",
29+
"ads.write",
30+
"media.write",
31+
"offline.access"
32+
]
33+
}
34+
}
35+
}
36+
}
37+
```
38+
39+
## What agents can do
40+
41+
| Category | Capabilities |
42+
| --- | --- |
43+
| Accounts | Read your ads accounts, funding instruments, and settings |
44+
| Campaigns | Create, update, pause, and read campaigns and line items |
45+
| Ads & creatives | Create and manage promoted ads and creatives |
46+
| Audiences | Read and manage targeting and audiences |
47+
| Pixels & conversions | Set up the X pixel and conversion tracking |
48+
| Analytics | Pull campaign, line item, and ad performance stats |
49+
50+
## Setup
51+
52+
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.
53+
54+
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.
55+
56+
## Scopes requested
57+
58+
`ads.read`, `ads.write`, `media.write`, `offline.access`
59+
60+
## Docs
61+
62+
- X Ads API: https://docs.x.com/x-ads-api/introduction
63+
- OAuth protected resource metadata: https://ads-api.x.com/.well-known/oauth-protected-resource
64+
- Authentication overview: https://docs.x.com/fundamentals/authentication/overview
65+
66+
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.
67+
68+
## License
69+
70+
MIT

‎third_party/x-ads/assets/logo.png‎

5.25 KB
Loading

‎third_party/x-ads/mcp.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"mcpServers": {
3+
"x-ads": {
4+
"type": "http",
5+
"url": "https://ads-api.x.com/mcp",
6+
"auth": {
7+
"CLIENT_ID": "NGdZYmo4VVp2T1BnRG55NlExOGQ6MTpjaQ",
8+
"scopes": [
9+
"ads.read",
10+
"ads.write",
11+
"media.write",
12+
"offline.access"
13+
]
14+
}
15+
}
16+
}
17+
}

0 commit comments

Comments
 (0)