X Ads MCP

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.

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.

Create a Native App in the X Developer Console with Read-and-Write permission and the matching callback URI, enable Ads Project, and connect the client to https://ads-api.x.com/mcp. Request only ads.read offline.access for reading; add ads.write only for approved changes.

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

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.

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.

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.

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.