X Ads

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

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @getmcpads/x-ads-mcp-server

Claude Code

claude mcp add x-ads -e 'X_ADS_ACCESS_TOKEN=<your x_ads_access_token>' -e 'X_ADS_ACCOUNT_IDS=<X_ADS_ACCOUNT_IDS>' -e 'X_ADS_SCOPES=<X_ADS_SCOPES>' -e 'X_ADS_ENABLE_WRITES=<X_ADS_ENABLE_WRITES>' -- npx -y @getmcpads/x-ads-mcp-server@1.1.1

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "x-ads": {
            "command": "npx",
            "args": [
                "-y",
                "@getmcpads/x-ads-mcp-server@1.1.1"
            ],
            "env": {
                "X_ADS_ACCESS_TOKEN": "<your x_ads_access_token>",
                "X_ADS_ACCOUNT_IDS": "<X_ADS_ACCOUNT_IDS>",
                "X_ADS_SCOPES": "<X_ADS_SCOPES>",
                "X_ADS_ENABLE_WRITES": "<X_ADS_ENABLE_WRITES>"
            }
        }
    }
}

Environment variables

X_ADS_ACCESS_TOKEN required secret User OAuth 2.0 token. Keep it secret.
X_ADS_ACCOUNT_IDS required Comma-separated allowed account IDs. Required even for reads.
X_ADS_SCOPES Scopes actually granted to the token, including ads.read.
X_ADS_ENABLE_WRITES true exposes 21 write tools. Defaults to false. Calls preview unless confirm is true.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

X Ads MCP server
What's new
Install this release
Configuration
Safety and coverage
Hosted option
Development
Tools
License
More from getmcpads

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.

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

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.0: Campaign and line item rename · October 23, 2026

Add x_ads_rename_campaign and x_ads_rename_line_item. Each previews by default, checks the account allowlist and the ads.write scope, then sends only account_id, the entity ID and name to X's update_campaign or update_line_item.
Declare both X endpoints in src/hosts.ts. New tests fail on a fetch without redirect handling or a timeout, and on any other host in src/.
Add test/readme-accuracy.test.mjs: every tool and the x-ads://guide resource are cited in the README, nothing else is, the counts match the code, and published prose has no em dash.
Update @modelcontextprotocol/sdk to 1.32.1 and regenerate package-lock.json. Require Node.js 22.23.4, 24.22.1, 26.12.1 or newer, and warn on stderr at startup on an older release. CI covers Node 22, 24 and 26.
Publish from a version tag with the new release.yml: npm with provenance, the GitHub release, then the MCP Registry. Dependabot now proposes weekly npm and monthly GitHub Actions updates.

Earlier releases

Version	Date	Highlights
1.0.1	September 23, 2026	Public repository restored
1.0.0	September 20, 2026	First 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.

git clone --branch v1.1.0 --depth 1 https://github.com/get-mcp-ads/x-ads-mcp-server.git
cd x-ads-mcp-server
npm ci
npm 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:

Variable	Purpose
`X_ADS_ACCESS_TOKEN`	Your user OAuth 2.0 access token. An app-only bearer token is not sufficient.
`X_ADS_ACCOUNT_IDS`	Required comma-separated account IDs, restricted to accounts the token may access.
`X_ADS_SCOPES`	Scopes actually granted to the token. Defaults to `ads.read`.
`X_ADS_ENABLE_WRITES`	Defaults 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: hello@getmcpads.com.

Development

npm run typecheck
npm run lint
npm run build
npm test
npm 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

Tool	Purpose
`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.

21 write tools

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

Tool	Purpose
`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.
`x_ads_rename_campaign`	Rename an X Ads campaign. The name is the only thing that changes.
`x_ads_rename_line_item`	Rename an X Ads line item (ad group). The name is the only thing that changes.

1 resource

URI	Contents
`x-ads://guide`	Account 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: hello@getmcpads.com.

Frequently asked questions

What is X Ads?

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

How do I install X Ads?

It runs on your machine. In Claude Code: claude mcp add x-ads -e 'X_ADS_ACCESS_TOKEN=<your x_ads_access_token>' -e 'X_ADS_ACCOUNT_IDS=<X_ADS_ACCOUNT_IDS>' -e 'X_ADS_SCOPES=<X_ADS_SCOPES>' -e 'X_ADS_ENABLE_WRITES=<X_ADS_ENABLE_WRITES>' -- npx -y @getmcpads/x-ads-mcp-server@1.1.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does X Ads need an API key?

Yes. It expects X_ADS_ACCESS_TOKEN, X_ADS_ACCOUNT_IDS, which you set in its configuration.

Is X Ads open source?

Yes. Its code is on GitHub under the Apache-2.0 license.

Who maintains X Ads?

It is published by get-mcp-ads. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: get-mcp-ads
Category: Marketing and sales
Runs: Local
GitHub stars: ★ 0
License: Apache-2.0
Language: TypeScript
Last commit: Oct 26, 2026
Open issues: 5
Version: 1.1.1
Published: Oct 26, 2026

com.getmcpads/x-ads

Similar servers

GhostPaw Affinity Local relationship model and social CRM for contacts, relationships, evidence, and comm...
Web Validator by DigestSEO Audit public webpages and supplied markup for HTML, CSS, SEO, JSON-LD, and link issues.
Quattr AI Visibility MCP SEO MCP for Claude and ChatGPT: GSC, market share, AI citations, and CWV.
PublishBuddy Schedule social posts, read analytics and make AI images and video for 10+ networks.
Oktio.app Instagram analytics, media kits, bio link and brand deals for creators, from your AI as...
Ssemble AI Clipping Create AI-powered short-form video clips from YouTube videos. Supports webhook callbacks.
AdRails Open-source, self-hosted Google Ads MCP server: guarded writes for AI agents. Your keys...
HeyLead — AI agent for LinkedIn outreach AI agent for LinkedIn outreach: finds the right people, writes in your voice, follows u...

Marketing and sales