Log inSubmit server
X Ads logo

X Ads

Reads X Ads campaigns, targeting, media, and performance, with optional preview-first write tools for selected accounts.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install X Ads

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "x-ads": {
      "command": "npx",
      "args": [
        "-y",
        "@getmcpads/x-ads-mcp-server"
      ],
      "env": {
        "X_ADS_ACCESS_TOKEN": "YOUR_VALUE_HERE",
        "X_ADS_ACCOUNT_IDS": "YOUR_VALUE_HERE",
        "X_ADS_SCOPES": "YOUR_VALUE_HERE",
        "X_ADS_ENABLE_WRITES": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The X Ads MCP server connects an MCP client to the X Ads API for account, campaign, targeting, media, post, and performance data. It runs locally over stdio with user OAuth 2.0 credentials and restricts requests to explicitly configured account IDs. Read tools are enabled by default, while write tools require configuration and explicit confirmation. Use it when an agent needs direct access to selected X Ads accounts rather than the hosted managed connection.

Use cases

  • Inspect campaign and line-item performance
  • Review targeting interests and locations
  • Check media-library objects and upload status
  • Prepare campaign changes for confirmation
  • List posts available for promotion

Key features

  • 25 read tools for X Ads data
  • 19 opt-in write tools
  • Preview-first write confirmation
  • Explicit account ID restrictions
  • Campaign and reach analytics
  • Native pagination and monetary micro-units

Tools44

What X Ads lets your agent do. Expand a tool for its parameters.

Self-reported~913 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 6d ago via OSV.dev · @getmcpads/x-ads-mcp-server (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads553Package downloads in the last 30 days.
Last commit26d agoMost recent push to the default branch.
Tools exposed44Callable tools this server registers over MCP.

How X Ads works

What the X Ads MCP server does

The X Ads MCP server exposes a reviewed subset of the official X Ads API as MCP tools. It provides 25 read tools for inspecting accessible advertising accounts, campaigns, line items, promoted posts, targeting criteria, posts available for promotion, funding instruments, web event tags, cards, media library objects, post previews, upload status, and related entities.

Reporting tools return account statistics such as impressions, engagements, and spend. Other read operations cover campaign reach, average frequency, active entities in a time window, targetable interests, and targetable locations. Native pagination, attribution data, and monetary values expressed in micro-units are retained.

The package also contains 19 write tools. These are disabled unless enabled in configuration, and include operations for campaign changes and media-related writes. Campaigns and line items are created paused.

How it works

The X Ads MCP server runs as a local Node.js process and communicates with an MCP client over stdio. Requests go directly from the process to X's API using the supplied user OAuth 2.0 access token; an app-only bearer token is not sufficient. Account IDs are explicitly configured, and checks run before requests are dispatched so tools cannot use accounts outside that selection.

Read operations are available by default. Write calls return a preview unless the request includes explicit confirmation. Before confirming a change, review the account, target, and parameters. Do not automatically retry a write when its result is uncertain; read the account and reconcile its state first.

The repository contains standalone native API tools. Hosted creative galleries, visual editors, MCP Apps interfaces, and other hosted product features are not part of this release.

Setup and configuration

Use Node.js 22.12 or newer. For the pinned source release, clone the repository, run npm ci, and build it with npm run build. Configure the MCP client to launch node with the absolute path to dist/cli.js.

Provide these environment variables through the client's secret configuration:

  • X_ADS_ACCESS_TOKEN: the user OAuth 2.0 access token.
  • X_ADS_ACCOUNT_IDS: comma-separated account IDs the token can access.
  • X_ADS_SCOPES: granted scopes; it defaults to ads.read.
  • X_ADS_ENABLE_WRITES: only the exact value true enables write tools; the default is false.

Use ads.read for reporting, ads.write for campaign changes, and media.write for uploads and media-library writes. The package accepts an existing token; it does not perform an OAuth browser flow or retain rotating refresh tokens. Renew expired tokens securely and restart the process. Uploads are limited to 4 MB and may consume X API credits.

Tools and capabilities

The X Ads MCP server includes tools for:

  • Listing and retrieving campaigns, line items, promoted posts, cards, media items, targeting criteria, web event tags, and ads accounts.
  • Querying account statistics, campaign reach, active entities, targeting interests, and locations.
  • Listing usable account posts, valid line-item placements, funding instruments, and media-library objects.
  • Rendering post previews and checking media upload processing status.
  • Creating or updating supported advertising entities when writes are enabled and explicitly confirmed.

Use tools/list or the repository's server-card.json to inspect current schemas. Saved arguments should be reviewed against the current tool definitions before reuse.

Limitations and notes

This X Ads MCP server does not automatically expose newly added upstream tools; its coverage is the reviewed subset shipped in the release. It requires explicit account selection and rejects unknown arguments. Write operations remain opt-in and preview-first, and activating advertising entities can spend budget.

Hosted and source releases may differ. The hosted option is intended for managed connections, including supported ChatGPT setups, while this local package is intended for clients that support stdio MCP. Tests use synthetic responses and do not modify live accounts.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about X Ads

X Ads is an MCP server that connects an MCP client to the X Ads API using your user OAuth 2.0 access token. Its main tools read accounts, campaigns, line items, targeting, media, posts, and performance, while optional write tools preview changes before explicit confirmation.

Clone the selected repository release, run `npm ci`, and build it with `npm run build`. Configure your MCP client to launch Node.js with the absolute path to `dist/cli.js`. Node.js 22.12 or newer is required.

It requires a user OAuth 2.0 access token in `X_ADS_ACCESS_TOKEN` and selected account IDs in `X_ADS_ACCOUNT_IDS`. An app-only bearer token is not sufficient. The server accepts an existing token and does not run the OAuth browser flow.

No, writes are disabled by default. Set `X_ADS_ENABLE_WRITES=true` to expose them, and provide the required granted scopes. Write calls preview their changes unless the request explicitly uses `confirm: true`.

Yes, X Ads works with Cursor when configured as a local stdio MCP server. The README also names Claude Desktop and Claude Code as supported stdio clients. Configure the client to run Node.js with the built `dist/cli.js` file.

Related MCP servers

All in Marketing All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewX Ads AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/x-ads?style=directory)](https://allmcps.com/mcp/x-ads)
HTML Embed
<a href="https://allmcps.com/mcp/x-ads"><img src="https://allmcps.com/api/badge/x-ads?style=directory" alt="X Ads on AllMCPs" /></a>