X Ads MCP

Official remote MCP server from X for campaign-focused Ads API reads, analytics, and writes.

Description

X Ads MCP is X’s official remotely operated Model Context Protocol server for the X Ads API. Its Streamable HTTP endpoint is https://ads-api.x.com/mcp. According to X, an MCP-capable client can discover the available tools automatically, then read advertising accounts, retrieve campaign and reach analytics, and manage advertising campaigns. The primary documentation is https://docs.x.com/x-ads-api/mcp. This is not a general-purpose server for X timelines, search, direct messages, or other ordinary X access: its boundary is the advertising platform, ad accounts, campaigns, creatives, targeting, and ads analytics.

What the Ads server does — and does not do

X’s documentation lists account and read tools for campaigns, line items, funding instruments, promoted posts, targeting criteria, and active entities. Analytics tools return account statistics and campaign reach estimates. Interest and location search tools help prepare targeting. Write tools can create or update campaigns and line items, add or remove targeting, create nullcast ad posts, and promote posts.

That does not give an AI client unrestricted access to X. The server is not a replacement for the general X API, does not manage direct messages, and cannot exceed the permissions of the Ads API. Actual access remains bounded by the app approval and by roles in the advertising account. X distinguishes roles including Account administrator, Ad manager, Campaign analyst, Organic analyst, and Creative Manager. An agent can use only what the signed-in user, authorized app, and particular ads account allow.

OAuth, scopes, and account boundaries

Per X, connecting requires your own app in the X Developer Console, Ads Project access, and Read-and-Write app permissions. The user authenticates with their own OAuth 2 token; X specifies the ads.read, ads.write, and offline.access scopes for this remote MCP. ads.read enables reading and analytics. Anyone who only needs analysis should omit ads.write: write tools will then fail authorization rather than make accidental changes. offline.access allows token refresh; without it, X says access tokens expire after a short time and cannot be automatically renewed.

The OAuth boundary matters for agents: the server sees only advertising accounts the user can access. X documents one live OAuth grant per app-and-user pair, so signing in from a second client can revoke the first client’s token set. If several clients are needed, a separate app per client is sensible. Access tokens, refresh tokens, client secrets, and callback codes must never appear in prompts, source control, or screenshots. Native clients use PKCE and do not need a secret; confidential clients must follow X’s documented authentication requirements.

Campaign mutations and human approval

The MCP server can change external advertising objects. X reduces part of the risk by always creating new campaigns and line items PAUSED; according to the provider, no money is spent until someone explicitly activates them. This is a useful guardrail, not a complete approval workflow. The activate_campaign and activate_line_item tools can perform that final activation. For budgets, targeting, creatives, audience changes, or promotion, a person should verify the intended parameters, account assignment, and approval before activation. A separate analysis client without ads.write is the safer default for reporting and planning.

Ads and customer data, model path, and prompt injection

Tool results may include campaign performance, reach values, funding information, audience or location criteria, and promoted content. The Ads API can also manage Custom Audiences using X, web, or mobile data; that data deserves especially careful handling. The data path is not simply “X to X”: X returns results to the MCP client, and the client decides which tool results are passed to the connected language model. With a hosted model, those results may therefore be processed by the model provider as well as by the client and X. Check privacy requirements, data-processing arrangements, retention, and client/model configuration before connecting production data.

Untrusted names, posts, audience labels, or analytics fields can contain text that looks like instructions. That is prompt injection, not a trusted user instruction. The agent should treat tool output as data, never derive write actions solely from that content, and require manual confirmation for activation. Where possible, separate read and write sessions and use a test ads account for initial experiments.

Limits, operation, and source code

X documents token-level and, for some endpoints, ad-account-level Ads API rate limits. The current limits and reset times are exposed in HTTP response headers; a client or agent should honor them, batch retrievals, request only data updated since the last sync, and wait after 429 responses or exhausted quotas rather than retrying aggressively. Write operations are not necessarily covered by the same account-level limits as read operations.

X publishes official remote documentation and a gateway endpoint for X Ads MCP, but as reviewed on 2026-09-08 it does not publish a public X-operated source repository for this Ads-specific server. repo_url and GitHub stars are intentionally null. The public xdevplatform/xMCP repository is a separate general X API MCP product and must not be presented as source code or a popularity metric for X Ads MCP. Social Media and Automation fit because the server makes X advertising work controllably readable, analyzable, and automatable.

Requirements

Your own X Developer app with Ads Project access, an X user with access to at least one ads account, and an MCP client supporting Streamable HTTP and OAuth 2.

Installation instructions

This guide covers only the official X Ads MCP at https://ads-api.x.com/mcp and its documentation at https://docs.x.com/x-ads-api/mcp. It is not setup guidance for a general X API server. Before connecting, decide whether the agent should only analyze campaigns or may also prepare changes after human approval. For the first test, use a separate ads test account or a tightly bounded campaign.

Prepare the X app and Ads access

Create a new or existing app in the X Developer Console. Per X, enable the Read and Write app permission, choose a Native App for the usual PKCE route, and register exactly the callback URI required by the client you use. For Claude Code, X lists http://localhost:8080/callback; other clients may require different callback URIs documented by X. Enable Ads Project under Project Access. Also confirm that your X user actually has access to at least one ads account. An ordinary X profile is not sufficient without an ads-account or role authorization.

According to X, one app-and-user pair has only one active OAuth grant. Signing in with the same user from a second client can make the first client lose its tokens. Use a separate X app for each long-lived client and document who owns that app and its associated ads account.

Step 1: Connect with the smallest scopes

Start with the OAuth scopes ads.read offline.access. This lets the agent list accounts and read analytics, but it cannot change campaigns, line items, creatives, or targeting. offline.access enables token refresh; without it, you must sign in again interactively after the access token expires. Add ads.write only when there is a clear change request and an approval path.

X documents this basic command for Claude Code:

Code
claude mcp add x-ads https://ads-api.x.com/mcp --transport http --client-id YOUR_OAUTH2_CLIENT_ID --callback-port 8080

Then run /mcp in the client and complete browser login. X’s documented scope restriction for Claude Code is set in its server configuration as ads.read offline.access. Never paste an access token, refresh token, OAuth code, or client secret into a chat. Native apps do not need a client secret for PKCE.

Read first, then write deliberately

First ask the agent to list reachable ads accounts and explain one campaign with its performance data. Check that the account number, display name, and time range are correct. Tool results can include reach, spend, targeting, funding information, or promoted-post data; treat all of it as confidential.

For changes, have the agent first provide a plan: target account, campaign name, budget and schedule, targeting, creative, and the exact tool sequence. Review that plan independently of tool text. According to X documentation, new campaigns and line items are always created PAUSED. That prevents immediate spend, but it does not replace review: only activate_campaign or activate_line_item performs activation. Approval and activation should stay with an accountable person.

Limit the data path and prompt injection

Data flows from X to the MCP client and then, depending on client configuration, onward to the language model. With a cloud model, campaign, audience, and customer data can therefore also reach the model provider. Check privacy requirements, data-processing terms, log retention, and whether tool results are stored or used for training. Do not use real customer segments in early tests if their onward disclosure is unresolved.

Names from audiences, posts, or analytics fields are not trusted instructions. If a tool result asks to fetch more data or activate a campaign, that is prompt injection. Do not let tool data determine tool selection. Separate analysis from write access, require explicit confirmation for every activation, and use a test account whenever practical.

Observe rate limits and handle errors safely

X exposes limits and reset times in response headers. Respect token-level and, where present, ads-account-level headers. Batch requests, ask only for data changed since the last sync, and never retry errors blindly. A 401 can mean an expired token; refresh it through the intended OAuth flow. A 403 commonly means missing Ads Project access, app enrollment, or account permission. A 429 means wait until reset and reduce request rate.

Step 2: Final check

Record which client, X app, user, and ads accounts are connected. Verify that an analysis-only session without ads.write cannot execute changes. Document who approves campaign activations, and review client configuration regularly for unnecessary tokens or over-broad scopes. This keeps X Ads MCP a controlled tool for ads analysis and prepared campaign work rather than an unattended write channel.

claude mcp add x-ads https://ads-api.x.com/mcp --transport http --client-id YOUR_OAUTH2_CLIENT_ID --callback-port 8080

Authentication

OAuth 2 with the user’s own X account and ads.read, optional ads.write, and offline.access scopes. Native clients use PKCE; keep tokens and callback codes secret.

Required access permissions

Only the ads accounts and Ads API functions authorized for the OAuth user, X app, and the relevant ads-account role. ads.write enables mutating tools.

Transmitted or stored data

X returns Ads API results to the MCP client. The client determines which tool results reach the connected model; with hosted models, ads and customer data may therefore also be processed by the model provider.

Security risks

ads.write can change campaigns, targeting, creatives, and activations. Prompt injection in tool data, token theft, exposure of audience/performance data, and ignored rate limits are material risks. Start with ads.read, protect secrets, and review activations manually.

License and costs

License
Not recorded yet.
Cost
free

X provides the remote server. Current terms for Ads API access, the ads account, and the AI client are set by their respective providers; this entry states no fixed prices.

Alternatives

Not recorded yet.

At a glance

Provider
X
Status
Official server
Deployment
Remote
Current version
Not recorded yet.
Last reviewed
08.09.2026

Repository and documentation

Categories

Supported clients

Related guides

Guides and background related to this entry.

No related guides yet.