Skip to content
MCP server

X Ads

Read X ad campaigns and stage preview-first changes from your AI assistant

Runs locallyStatus and history
Install
Pricing
Freemium
Platforms
Web, API, CLI
Runs
Locally
Version
1.1.2
Listing updated
3 days ago

About X Ads

X Ads is a freemium MCP server for marketing and seo. It runs locally on your machine and is started by your AI client.

The X Ads server is built around X's own Ads MCP endpoint at ads-api.x.com. The hosted Get MCP Ads version relays it with the token from your X sign-in, then adds account selection, previews before each change, media uploads, alerts and Google Sheets. You tick which ad accounts to share and the assistant sees only those.

Reads cover campaigns, ad groups and promoted posts, with account statistics (75 metrics) and reach and average frequency. Writes include budgets, schedules, frequency caps and targeting, and new campaigns and ad groups are created paused. Website cards take one image or video, or a carousel of 2 to 6, with a single destination. A new campaign needs a funding source on the X account.

The open-source npm package (25 read tools, 21 writes) runs locally over stdio with your own OAuth 2.0 user token. X_ADS_ACCOUNT_IDS is required even for reads, and writes stay off unless X_ADS_ENABLE_WRITES=true, with each call previewing until confirmed.

Install

Run in a terminal

claude mcp add x-ads --env X_ADS_ACCESS_TOKEN='<X_ADS_ACCESS_TOKEN>' --env X_ADS_ACCOUNT_IDS='<X_ADS_ACCOUNT_IDS>' -- npx -y @getmcpads/x-ads-mcp-server

Add to claude_desktop_config.json

{
  "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>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "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>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "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>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "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>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "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>"
      }
    }
  }
}

Configuration

  • X_ADS_ACCESS_TOKENUser OAuth 2.0 token. Keep it secret.Required
  • X_ADS_ACCOUNT_IDSComma-separated allowed account IDs. Required even for reads.Required
  • X_ADS_SCOPESScopes actually granted to the token, including ads.read.
  • X_ADS_ENABLE_WRITEStrue exposes 21 write tools. Defaults to false. Calls preview unless confirm is true.

Tools this server provides (12)

Taken from the project documentation; the running server may differ.

x_ads_list_campaigns
Lists X campaigns for the selected ad accounts.
x_ads_get_account_stats
Returns account statistics by campaign, ad group and promoted post.
x_ads_get_campaign_reach
Returns reach and average frequency for a campaign.
x_ads_list_targeting_criteria
Lists targeting set on an ad group.
x_ads_update_line_item
Updates an ad group's budget, schedule or frequency cap after preview.
x_ads_create_campaign
Creates a paused campaign.
x_ads_create_line_item
Creates a paused ad group.
x_ads_add_targeting_criterion
Adds a targeting criterion to an ad group.
x_ads_upload_media
Uploads media through X's media API.
x_ads_create_card
Creates a website card.
x_ads_create_ad_post
Creates an ad post.
x_ads_promote_post
Promotes a post.

What it does

Account allowlist
Requires explicit ad account IDs, even for read calls.
Reach and frequency
Reports reach and average frequency by campaign, ad group and promoted post.
Preview before change
Write calls preview first and apply only when confirmed.
Paused creation
New campaigns and ad groups start paused.
Website cards
Builds cards from one image or video, or a 2-6 item carousel.
Writes off by default
21 write tools appear only when enabled.

Good for

  • Pull spend and clicks by campaign for the last week
  • Check which targeting an ad group uses
  • Raise a daily budget and cap frequency after a preview
  • Upload a video and promote it as a website card
  • Check reach for a seasonal campaign

Pricing

Freemium, from $39 a month

Hosted: Free (1 ad account, 200 requests/month), Pro $39/mo, Team $99/mo; open-source npm server is Apache 2.0

Prices change. Check getmcpads.com before you buy.

X Ads FAQ

Does it need an app-only token?

No; the README says an app-only bearer token is not sufficient and a user OAuth 2.0 token is needed.

Can it change my campaigns by default?

No. Writes are disabled until `X_ADS_ENABLE_WRITES` is true, and calls preview unless confirm is true.

What Node version is required?

Node.js 22.23.4, 24.22.1, 26.12.1 or newer.

Is there a free hosted tier?

Yes, one ad account and 200 requests a month with no card.

Is X Ads free?

X Ads has a free plan, with paid plans for more usage or features. Paid plans start at $39 a month.

How do I add X Ads to Claude Code?

Run this command in your terminal: claude mcp add x-ads --env X_ADS_ACCESS_TOKEN='<X_ADS_ACCESS_TOKEN>' --env X_ADS_ACCOUNT_IDS='<X_ADS_ACCOUNT_IDS>' -- npx -y @getmcpads/x-ads-mcp-server

What are the best alternatives to X Ads?

The closest alternatives to X Ads are Google Ads + Meta Ads + SEO/GEO MCP, Calven, MCP, Red Center Studio free tools and ASOScan.

Alternatives to X Ads

  1. Hosted MCP connector for managing Google Ads, Meta Ads, GA4 and Search Console from chat

    • 8 tools
    • Remote
    • Freemium
    • 8.1K GitHub stars
    • Marketing and SEO
  2. Calven

    MCP server

    Product marketing context from Calven delivered into Claude, ChatGPT and other AI tools

    Not checked yet
    • Remote
    • Free trial
    • 3 GitHub stars
    • Marketing and SEO
  3. MCP

    MCP server

    MCP server for planning, scheduling and measuring social and ad campaigns with approvals

    • Remote
    • Freemium
    • Marketing and SEO
  4. Free website checks for AI readiness, DNS dependencies, domain health and Bubble errors

    • 5 tools
    • Remote
    • Free
    • Marketing and SEO
  5. ASOScan

    MCP server

    ASO data for your own iOS and Android apps: rankings, keywords, reviews, scores

    • Remote
    • Free trial
    • Marketing and SEO
  6. PostBaton

    MCP server

    Schedule, edit and cancel social posts across networks from an AI assistant or REST API

    Not checked yet
    • Remote
    • Freemium
    • Marketing and SEO