# X Ads [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/get-mcp-ads/x-ads-mcp-server  
**GitHub Stars:** 0  
**npm Downloads (last month):** 553  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/x-ads

## Description
X Ads MCP server: 25 read tools, 19 opt-in preview-first writes.

## Tools
Capabilities this server exposes over MCP:

- **x_ads_list_ads_accounts** — List the ads accounts the authenticated user can access
- **x_ads_list_campaigns** — List campaigns for an account
- **x_ads_get_campaign** — Get a single campaign by ID
- **x_ads_list_funding_instruments** — List funding instruments (payment sources) for an ads account
- **x_ads_list_line_items** — List line items (ad groups) for an ads account
- **x_ads_get_line_item** — Get a single line item by ID
- **x_ads_list_promoted_posts** — List promoted posts (promoted tweets) for an ads account
- **x_ads_list_targeting_criteria** — List targeting criteria for an ads account's line items
- **x_ads_list_account_posts** — List posts (tweets) usable for promotion by an ads account
- **x_ads_list_web_event_tags** — List the website conversion event tags (pixels) in an ads account; a tag's id is what a conversion line item takes as its primary_web_event_tag
- **x_ads_list_line_item_placements** — List valid placement combinations per line item product type
- **x_ads_get_account_stats** — Get synchronous analytics (impressions, engagements, spend) for an ads account
- **x_ads_get_active_entities** — List which ads entities had metrics change in a time window (use before requesting account stats)
- **x_ads_get_campaign_reach** — Get reach and average-frequency metrics for campaigns
- **x_ads_search_targeting_interests** — Search targetable interest categories by name.
- **x_ads_search_targeting_locations** — Search targetable locations by name.
- **x_ads_list_cards** — List the cards in an ads account
- **x_ads_get_card** — Get a single card by ID
- **x_ads_list_media_library** — List the media library objects in an ads account
- **x_ads_get_media_library_item** — Get a single media library object by media key
- **x_ads_get_promoted_post** — Get a single promoted post by ID
- **x_ads_get_targeting_criterion** — Get a single targeting criterion by ID
- **x_ads_list_post_previews** — Get rendered HTML previews for published or scheduled posts
- **x_ads_get_web_event_tag** — Get a single website conversion event tag by ID
- **x_ads_get_media_upload_status** — Read processing status of an upload owned by the connected X user.
- **x_ads_create_campaign** — Create a campaign in an ads account.
- **x_ads_update_campaign** — Rename a campaign or pause it (entity_status=PAUSED).
- **x_ads_activate_campaign** — Activate a campaign (set entity_status=ACTIVE).
- **x_ads_create_line_item** — Create a line item (ad group) under a campaign.
- **x_ads_update_line_item** — Update a line item's bid, budget, name, schedule, placements, goal, pacing, audience expansion (set audience_expansion=EXPANDED to turn on Optimized Targeting) or entity_status.
- **x_ads_activate_line_item** — Activate a line item (set entity_status=ACTIVE).
- **x_ads_promote_post** — Attach post(s) to a line item as its ad creative(s).
- **x_ads_add_targeting_criterion** — Add one targeting criterion to a line item (call once per criterion).
- **x_ads_remove_targeting** — Remove a targeting criterion from its line item (undo a targeting mistake).
- **x_ads_create_ad_post** — Compose a promoted-only ("nullcasted") post to use as an ad creative.
- **x_ads_create_card** — Create a card from a JSON components payload.
- **x_ads_delete_card** — Delete a card from an ads account.
- **x_ads_create_media_library_item** — Register an existing media key as a named item in the account's media library.
- **x_ads_delete_media_library_item** — Delete a media library object from an ads account Preview by default.
- **x_ads_update_media_library_item** — Update a media library object's metadata (e.g. name, title, description) Preview by default.
- **x_ads_create_web_event_tag** — Create a website conversion event tag (pixel); the returned id can be set as a line item's primary_web_event_tag Preview by default.
- **x_ads_delete_web_event_tag** — Delete a website conversion event tag Preview by default.
- **x_ads_update_web_event_tag** — Update a website conversion event tag Preview by default.
- **x_ads_upload_media** — Upload an image, GIF or MP4 clip to X.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "x-ads": {
    "command": "npx",
    "args": ["-y","@getmcpads/x-ads-mcp-server"],
    "env": {
      "X_ADS_ACCESS_TOKEN": "",
      "X_ADS_ACCOUNT_IDS": "",
      "X_ADS_SCOPES": "",
      "X_ADS_ENABLE_WRITES": ""
    }
  }
}
```

**Requires environment variables:** `X_ADS_ACCESS_TOKEN`, `X_ADS_ACCOUNT_IDS`, `X_ADS_SCOPES`, `X_ADS_ENABLE_WRITES` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/x-ads/readme_