X Ads — Claude Code MCP server: what it does, how to install
Connects X Ads accounts to your MCP client via direct stdio. Inspect campaign stats, check targeting parameters, and prepare guarded updates.
claude mcp add --env X_ADS_ACCESS_TOKEN=<X_ADS_ACCESS_TOKEN> --env X_ADS_ACCOUNT_IDS=<X_ADS_ACCOUNT_IDS> --env X_ADS_SCOPES=<X_ADS_SCOPES> --env X_ADS_ENABLE_WRITES=<X_ADS_ENABLE_WRITES> --transport stdio x-ads -- npx -y @getmcpads/x-ads-mcp-serverWhat X Ads does
This MCP server links your assistant directly to the X Ads API over stdio. It provides 25 read operations and 21 write operations. The assistant can pull delivery metrics, check line-item targeting settings, and inspect accounts filtered through an explicit allowlist.
Mutations stay off out of the box. Exposing write tools demands setting X_ADS_ENABLE_WRITES strictly to true alongside the ads.write permission scope. Every mutation runs in preview mode first; actually applying an update requires sending confirm: true. Newly drafted entities begin in a paused state.
The server will fail on app-only bearer tokens because the official API demands a user OAuth 2.0 token. No browser authorization flow or refresh token loop exists here: you must provide fresh tokens manually and restart the process. The runtime requires Node.js 22.23.4, 24.22.1, or 26.12.1 at minimum.
What it helps with
- retrieve campaign performance and spend figures from X Ads
- audit targeting parameters across specified ad account IDs
- preview and apply campaign or line item renames safely
- upload media files under 4 MB directly to the ad library
Example prompts for the agent
- Inspect performance metrics for all active campaigns in my configured accounts.
- Preview a name change for line item 987654 to Retargeting Tier 1.
- Apply the renamed campaign 123456 with confirm set to true.
How to install X Ads
Platform CLI
claude mcp add --env X_ADS_ACCESS_TOKEN=<X_ADS_ACCESS_TOKEN> --env X_ADS_ACCOUNT_IDS=<X_ADS_ACCOUNT_IDS> --env X_ADS_SCOPES=<X_ADS_SCOPES> --env X_ADS_ENABLE_WRITES=<X_ADS_ENABLE_WRITES> --transport stdio x-ads -- npx -y @getmcpads/x-ads-mcp-serverReplace <…> with your own values
Platform CLI
codex mcp add x-ads --env X_ADS_ACCESS_TOKEN=<X_ADS_ACCESS_TOKEN> --env X_ADS_ACCOUNT_IDS=<X_ADS_ACCOUNT_IDS> --env X_ADS_SCOPES=<X_ADS_SCOPES> --env X_ADS_ENABLE_WRITES=<X_ADS_ENABLE_WRITES> -- npx -y @getmcpads/x-ads-mcp-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"x-ads": {
"command": "npx",
"args": [
"-y",
"@getmcpads/x-ads-mcp-server"
],
"env": {
"X_ADS_ACCESS_TOKEN": "<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>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"x-ads": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@getmcpads/x-ads-mcp-server"
],
"env": {
"X_ADS_ACCESS_TOKEN": "<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>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e X_ADS_ACCESS_TOKEN=<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> x-ads npx -y @getmcpads/x-ads-mcp-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about X Ads
How do I install X Ads in Claude Code?
Run claude mcp add x-ads -e X_ADS_ACCESS_TOKEN=<X_ADS_ACCESS_TOKEN> -e X_ADS_ACCOUNT_IDS=<X_ADS_ACCOUNT_IDS> -- npx -y @getmcpads/x-ads-mcp-server in your terminal. Replace the placeholders with your actual user OAuth 2.0 token and account IDs.
What does the X Ads MCP server do?
It exposes 25 read tools and 21 preview-first write tools for the X Ads API. Assistants can fetch performance metrics, inspect targeting criteria, and safely modify ad assets.
What happens if an access token expires?
The server does not manage automatic refresh tokens or OAuth redirects. You have to obtain a valid access token yourself and restart your MCP client process.
