X Ads

com.getmcpadsPublished by getmcpads.comv1.1.1Updated Nov 2, 2026

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

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Local stdio MCP server that lets an assistant read X Ads accounts, campaigns, line items, targeting and performance, with optional preview-first write tools.

What you can do
  • List and inspect ads accounts, campaigns, line items, funding instruments, cards, media library items, promoted posts and web event tags
  • Read targeting criteria, placements, and search targetable interests and locations by name
  • Pull account analytics, active entities and campaign reach metrics
  • Optionally, when writes are enabled, create, rename, pause or activate campaigns and line items, attach posts, add or remove targeting, manage cards, media and conversion tags, and upload media
  • Writes preview first and only apply when repeated with confirm set to true
When to use it
Useful when you want an assistant to review X Ads performance, audit campaign structure and targeting, or prepare and confirm campaign changes for specific accounts without leaving the MCP client.
Requirements
Runs locally as an npm package over stdio, started with Node.js (version 22.23.4, 24.22.1, 26.12.1 or newer) and an MCP client that supports stdio. Needs a user OAuth 2.0 access token in X_ADS_ACCESS_TOKEN (an app-only bearer token is not sufficient), comma-separated X_ADS_ACCOUNT_IDS, and optionally X_ADS_SCOPES and X_ADS_ENABLE_WRITES. The package does not run an OAuth flow or refresh tokens.
Before you install
X_ADS_ACCESS_TOKEN is a secret and must be kept private; the server accepts a token but does not refresh it, so it must be renewed and the server restarted. Writes are off unless X_ADS_ENABLE_WRITES is exactly true, and enabling them exposes 21 tools that change or delete campaigns, targeting, cards, media and conversion tags. Activating campaigns or line items can spend advertising budget, and media uploads can consume X API credits. Review each preview before confirming, and do not retry an…

Installation

In SourceWeft

  1. Open X Ads in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

X Ads MCP server

Bring your X Ads accounts into your MCP client.

Read campaigns and performance, inspect targeting and prepare changes for explicitly selected accounts.

[Release] [CI] [Smithery] [License: Apache 2.0] [Node]

Watch the film · What's new · Install · Tool reference · Try hosted getmcpads

[Watch the getmcpads film: every ad account in one conversation with your AI assistant]

Play the 45-second film

The film shows hosted getmcpads with sample data. Its MCP Apps, from creative galleries and alerts to Google Sheets exports and bulk launches, belong to the hosted product. This repository provides the standalone native API tools.

25 read tools · 21 write tools, disabled by default.

Run locally with your own platform credentials and a client that supports stdio MCP, such as Claude Desktop, Claude Code or Cursor. Your requests go directly to the platform. For managed connections, including supported ChatGPT setups, use the hosted option.

What's new

v1.1.1: Zod 4 security update · October 26, 2026

  • Update zod to 4.6.7. Every Zod release before 4.6.6 is covered by the high-severity advisory GHSA-mrhx-c7xc-m3w5: validating an oversized constrained collection can exhaust memory, and no Zod 3 release carries the fix. npm audit --omit=dev reports no vulnerability again.
  • Keep the Zod 3 validation behaviour. A parameter default is still validated and completed before use, so an omitted object must still supply its required fields.
  • Keep each parameter's own description when the parameter is optional or has a default. Zod 4 stores a description on the wrapped schema only, so the shared fallback description could otherwise replace it.
  • Tool names, parameters and descriptions published over MCP are unchanged. server-card.json is regenerated with Zod 4's JSON Schema output, which spells some constraints differently.

Earlier releases

VersionDateHighlights
1.1.0October 23, 2026Campaign and line item rename
1.0.1September 23, 2026Public repository restored
1.0.0September 20, 2026First standalone release

Full changelog · All releases

Source synchronization: SOURCE_SYNC.md.

Upgrade notes

Requires Node.js 22.23.4, 24.22.1, 26.12.1 or a newer release. These carry the October 2026 security fixes, and the server prints a warning on stderr when it runs on an older one. CI covers Node 22, 24 and 26.

No breaking change. Configuration variables and accepted values are unchanged: X_ADS_ACCOUNT_IDS stays required and only true enables writes, as in 1.0. The rename tools are writes: they appear only with X_ADS_ENABLE_WRITES=true and need ads.write in X_ADS_SCOPES.

Read the current tool schemas before reusing saved arguments. Writes remain optional and require explicit confirmation. Hosted creative integrations and MCP Apps UI are outside this release.

Install this release

This is a GitHub source release. npm and MCP Registry versions are published separately. The commands below select this exact version.

bash
git clone --branch v1.1.1 --depth 1 https://github.com/get-mcp-ads/x-ads-mcp-server.gitcd x-ads-mcp-servernpm cinpm run build

Configure your MCP client to run node with the absolute path to dist/cli.js and the platform credentials documented below.

Prefer a managed connection? Use X Ads with hosted getmcpads. Connect your account, select the data your assistant may access and use the hosted MCP connection. See the site for current features and plans.

Configuration

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

VariablePurpose
X_ADS_ACCESS_TOKENYour user OAuth 2.0 access token. An app-only bearer token is not sufficient.
X_ADS_ACCOUNT_IDSRequired comma-separated account IDs, restricted to accounts the token may access.
X_ADS_SCOPESScopes actually granted to the token. Defaults to ads.read.
X_ADS_ENABLE_WRITESDefaults to false. Only the exact value true exposes writes.

Obtain your token and Ads Project access using X's official setup guide. Use ads.read for reporting, ads.write for campaign changes and media.write for uploads and media-library writes. Setting X_ADS_SCOPES does not grant permissions. This package accepts a token; it does not run an OAuth browser flow or persist rotating refresh tokens. When the token expires, renew it securely and restart the server.

Safety and coverage

Writes preview by default. Review the exact account, target and parameters before repeating the call with confirm: true. Campaigns and line items are created paused. Activation can spend advertising budget. Media uploads can consume X API credits and are limited to 4 MB. Do not retry a write automatically when its result is uncertain. Read the account and reconcile it first. Selected-account checks apply before dispatch and filter account discovery responses. Unknown arguments are rejected. Native pagination, attribution and monetary _micro fields are preserved. A micro unit is one millionth of the account currency.

This server exposes a reviewed subset of the official API. It does not automatically expose new upstream tools. Native media reads and writes are included. Hosted creative galleries, visual editors and MCP Apps UI are excluded. Use tools/list or server-card.json for exact schemas and the official API reference for provider details.

Hosted option

getmcpads for X Ads manages the hosted connection and account selection. Hosted and source releases can differ. Contact: [email protected].

Development

bash
npm run typechecknpm run lintnpm run buildnpm testnpm run catalog

All tests run offline with synthetic responses. No live account is changed.

Tools

Every tool is listed below. See server-card.json for complete parameter and output schemas.

25 read tools
ToolPurpose
x_ads_list_ads_accountsList the ads accounts the authenticated user can access
x_ads_list_campaignsList campaigns for an account
x_ads_get_campaignGet a single campaign by ID
x_ads_list_funding_instrumentsList funding instruments (payment sources) for an ads account
x_ads_list_line_itemsList line items (ad groups) for an ads account
x_ads_get_line_itemGet a single line item by ID
x_ads_list_promoted_postsList promoted posts (promoted tweets) for an ads account
x_ads_list_targeting_criteriaList targeting criteria for an ads account's line items
x_ads_list_account_postsList posts (tweets) usable for promotion by an ads account
x_ads_list_web_event_tagsList 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_placementsList valid placement combinations per line item product type
x_ads_get_account_statsGet synchronous analytics (impressions, engagements, spend) for an ads account
x_ads_get_active_entitiesList which ads entities had metrics change in a time window (use before requesting account stats)
x_ads_get_campaign_reachGet reach and average-frequency metrics for campaigns
x_ads_search_targeting_interestsSearch targetable interest categories by name.
x_ads_search_targeting_locationsSearch targetable locations by name.
x_ads_list_cardsList the cards in an ads account
x_ads_get_cardGet a single card by ID
x_ads_list_media_libraryList the media library objects in an ads account
x_ads_get_media_library_itemGet a single media library object by media key
x_ads_get_promoted_postGet a single promoted post by ID
x_ads_get_targeting_criterionGet a single targeting criterion by ID
x_ads_list_post_previewsGet rendered HTML previews for published or scheduled posts
x_ads_get_web_event_tagGet a single website conversion event tag by ID
x_ads_get_media_upload_statusRead processing status of an upload owned by the connected X user.
21 write tools

Disabled by default. Calls preview unless explicitly confirmed. Check the configuration and exact schema before use.

ToolPurpose
x_ads_create_campaignCreate a campaign in an ads account.
x_ads_update_campaignRename a campaign or pause it (entity_status=PAUSED).
x_ads_activate_campaignActivate a campaign (set entity_status=ACTIVE).
x_ads_create_line_itemCreate a line item (ad group) under a campaign.
x_ads_update_line_itemUpdate 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_itemActivate a line item (set entity_status=ACTIVE).
x_ads_promote_postAttach post(s) to a line item as its ad creative(s).
x_ads_add_targeting_criterionAdd one targeting criterion to a line item (call once per criterion).
x_ads_remove_targetingRemove a targeting criterion from its line item (undo a targeting mistake).
x_ads_create_ad_postCompose a promoted-only ("nullcasted") post to use as an ad creative.
x_ads_create_cardCreate a card from a JSON components payload.
x_ads_delete_cardDelete a card from an ads account.
x_ads_create_media_library_itemRegister an existing media key as a named item in the account's media library.
x_ads_delete_media_library_itemDelete a media library object from an ads account Preview by default.
x_ads_update_media_library_itemUpdate a media library object's metadata (e.g. name, title, description) Preview by default.
x_ads_create_web_event_tagCreate 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_tagDelete a website conversion event tag Preview by default.
x_ads_update_web_event_tagUpdate a website conversion event tag Preview by default.
x_ads_upload_mediaUpload an image, GIF or MP4 clip to X.
x_ads_rename_campaignRename an X Ads campaign. The name is the only thing that changes.
x_ads_rename_line_itemRename an X Ads line item (ad group). The name is the only thing that changes.
1 resource
URIContents
x-ads://guideAccount scoping, units, write workflow and media limits for this server

License

Apache License 2.0. See NOTICE.

More from getmcpads

Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads

Maintained by Emmanuel at getmcpads. Questions: [email protected].

Source: README.md at commit 5790b87

Tools

25

x_ads_list_ads_accounts

x ads list ads accounts

List the ads accounts the authenticated user can access Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersaccount_ids

x_ads_list_campaigns

x ads list campaigns

List campaigns for an account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersqcountcursorsort_byaccount_idrequiredwith_draftcampaign_idswith_deletedwith_total_countfunding_instrument_ids

x_ads_get_campaign

x ads get campaign

Get a single campaign by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersaccount_idrequiredcampaign_idrequiredwith_deleted

x_ads_list_funding_instruments

x ads list funding instruments

List funding instruments (payment sources) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parameterscountcursorsort_byaccount_idrequiredwith_deletedwith_total_countfunding_instrument_ids

x_ads_list_line_items

x ads list line items

List line items (ad groups) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersqcountcursorsort_byaccount_idrequiredwith_draftcampaign_idswith_deletedline_item_idswith_total_countfunding_instrument_ids

x_ads_get_line_item

x ads get line item

Get a single line item by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersaccount_idrequiredline_item_idrequiredwith_deleted

x_ads_list_promoted_posts

x ads list promoted posts

List promoted posts (promoted tweets) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parameterscountcursorsort_byaccount_idrequiredwith_deletedline_item_idswith_total_countpromoted_tweet_ids

x_ads_list_targeting_criteria

x ads list targeting criteria

List targeting criteria for an ads account's line items Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parameterslangcountcursorsort_byaccount_idrequiredwith_deletedline_item_idsrequiredwith_total_counttargeting_criterion_ids

x_ads_list_account_posts

x ads list account posts

List posts (tweets) usable for promotion by an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parameterscountcursoruser_idtrim_usertweet_idsaccount_idrequiredtweet_typerequiredtimeline_typeinclude_mentions_and_replies

x_ads_list_web_event_tags

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 Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parameterscountcursorsort_byaccount_idrequiredwith_deletedwith_total_countweb_event_tag_ids

x_ads_list_line_item_placements

x ads list line item placements

List valid placement combinations per line item product type Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersproduct_type

x_ads_get_account_stats

x ads get account stats

Get synchronous analytics (impressions, engagements, spend) for an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersentityrequiredend_timerequiredplacementrequiredaccount_idrequiredentity_idsrequiredstart_timerequiredgranularityrequiredmetric_groupsrequired

x_ads_get_active_entities

x ads get active entities

List which ads entities had metrics change in a time window (use before requesting account stats) Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersentityrequiredend_timerequiredaccount_idrequiredstart_timerequiredcampaign_idsline_item_idsfunding_instrument_ids

x_ads_get_campaign_reach

x ads get campaign reach

Get reach and average-frequency metrics for campaigns Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersend_timerequiredaccount_idrequiredstart_timerequiredcampaign_idsrequired

x_ads_search_targeting_interests

x ads search targeting interests

Search targetable interest categories by name. Use this to find the targeting_value IDs required by add_targeting_criterion for INTEREST-type criteria. Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersqcountcursor

x_ads_search_targeting_locations

x ads search targeting locations

Search targetable locations by name. Use this to find the targeting_value IDs required by add_targeting_criterion for LOCATION-type criteria. Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersqcountcursorcountry_codelocation_type

x_ads_list_cards

x ads list cards

List the cards in an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersqcountcursorsort_bycard_idscard_urisaccount_idrequiredcard_typeswith_deletedwith_total_countinclude_legacy_cards

x_ads_get_card

x ads get card

Get a single card by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parameterscard_idrequiredaccount_idrequiredwith_deleted

x_ads_list_media_library

x ads list media library

List the media library objects in an ads account Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersqcountcursoraccount_idrequiredmedia_type

x_ads_get_media_library_item

x ads get media library item

Get a single media library object by media key Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersmedia_keyrequiredaccount_idrequired

x_ads_get_promoted_post

x ads get promoted post

Get a single promoted post by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersaccount_idrequiredwith_deletedpromoted_tweet_idrequired

x_ads_get_targeting_criterion

x ads get targeting criterion

Get a single targeting criterion by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parameterslangaccount_idrequiredwith_deletedtargeting_criterion_idrequired

x_ads_list_post_previews

x ads list post previews

Get rendered HTML previews for published or scheduled posts Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersuser_idtweet_idsrequiredaccount_idrequiredtweet_typerequired

x_ads_get_web_event_tag

x ads get web event tag

Get a single website conversion event tag by ID Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Parametersaccount_idrequiredwith_deletedweb_event_tag_idrequired

x_ads_get_media_upload_status

x ads get media upload status

Read processing status of an upload owned by the connected X user. Media uploads are user-owned until registered in the selected account's media library.

Parametersmedia_idrequiredaccount_idrequired

Version history

3
  1. v1.1.1LatestOct 26, 2026
  2. v1.1.0Oct 23, 2026
  3. v1.0.1Sep 23, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts