# X Ads (Twitter) MCP MCP

> X Ads (Twitter) MCP. This connector lets your AI agent run a full audit of your paid advertising campaigns directly from your workflow. You can list all ad accounts, check line item performance, retrieve deep analytics for ROI tracking, and review creative assets without logging into any dashboard. It’s total oversight for advertisers.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** ad-campaigns, performance-analytics, marketing-audit, real-time-bidding, social-advertising, roi-tracking

## Description

Managing X Ads campaigns used to mean jumping between multiple dashboards, exporting CSVs, and stitching together data points just to figure out where your spend went. This MCP lets your agent orchestrate that entire process in a single conversation. You can ask it to list all ad accounts, audit specific line items for performance status, or pull detailed analytics across flexible date ranges to understand true ROI. The whole thing becomes a natural dialogue with your ads data.

Because advertising credentials are so sensitive, the system handles everything through a zero-trust proxy—your keys never sit on a disk. This means you get full ad visibility and granular control over complex campaigns, whether you're boosting website traffic or running scaled video views. You can even chain this MCP with other systems in your catalog to build automations that span multiple platforms using the power of Vinkius.

It acts like an always-on ad analyst for your business. Your agent pulls everything together—from account setup details to campaign performance reports—so you never have to manually touch a dashboard again.

## Tools

### get_ad_account
Gets specific details for one ad account using its ID.

### list_ad_accounts
Lists all ad accounts you manage within X Ads.

### list_ads
Retrieves a list of individual ads tied to an account.

### list_campaigns
Lists all advertising campaigns for a specific ad account.

### list_funding_instruments
Retrieves a list of payment methods and funding sources used by an account.

### list_line_items
Lists the specific line items that make up your ad campaigns for an account.

### get_analytics
Retrieves performance metrics and analytics data for advertising entities over time.

### get_campaign
Use list_campaigns first to find the campaign ID.

Get full details for a specific campaign by its ID

### get_line_item
Use list_line_items first to find the line item ID.

Get full details for a specific line item by its ID

### list_media_creatives
Use this to audit which creative assets are currently active.

List all media creative assets (images and videos) used in an X Ads account

### list_promoted_tweets
Gets a list of all promoted tweets and associated creative assets.

### list_tailored_audiences
Useful for understanding retargeting strategy.

List custom audiences (tailored audiences) for retargeting and CRM matching

### list_targeting_criteria
Requires both the account ID and line item ID.

List all targeting criteria applied to a specific line item

## Prompt Examples

**Prompt:** 
```
List all my X ad accounts and tell me which ones are active.
```

**Response:** 
```
You have 2 ad accounts:

1. **SaaS Growth** (ID: abc123) — Active, funding via credit card ending in 4242
2. **Product Launch Q2** (ID: def456) — Paused since June 3

Would you like me to pull the active campaigns for 'SaaS Growth'?
```

**Prompt:** 
```
Show me the engagement metrics for all line items in account abc123, from June 1 to June 14.
```

**Response:** 
```
Here are the engagement metrics for your 3 line items between June 1–14:

| Line Item | Impressions | Clicks | Spend | CTR |
|---|---|---|---|---|
| Retargeting — Webinar | 42,100 | 1,230 | $312 | 2.92% |
| Lookalike — SaaS | 38,500 | 890 | $278 | 2.31% |
| Brand Awareness | 91,200 | 620 | $445 | 0.68% |

The retargeting line item is outperforming by CTR. Would you like a day-by-day breakdown?
```

**Prompt:** 
```
Which promoted tweets are running right now on account abc123?
```

**Response:** 
```
You have 4 promoted tweets active on that account:

1. "Just launched our AI integration..." — Linked to 'SaaS Growth' campaign
2. "Watch the full product demo..." — Linked to 'Video Launch'
3. "Free trial — no credit card..." — Linked to 'Retargeting'
4. "Case study: 3x pipeline in 60 days..." — Linked to 'Lookalike'

Want me to pull engagement stats for any of these?
```

## Capabilities

### List all accounts
Gets a list of every connected X Ads account and its basic metadata.

### Audit campaigns and ads
Retrieves structured lists of campaigns, line items, and individual ad creatives within an account.

### Retrieve performance data
Pulls detailed advertising analytics for a specified period, letting you calculate ROI.

### Check funding methods
Lists all accepted payment and billing instruments tied to an account.

### Identify promoted content
Gets a list of all active promoted tweets and creative assets.

## Use Cases

### Diagnosing poor campaign ROI after launch
The manager asks, 'Why did our Q2 engagement rate drop?' The agent responds by running get_analytics for the last 90 days and cross-referencing the data with list_line_items to pinpoint which specific ad format or spending segment failed.

### Preparing an audit before a budget review
The analyst runs a full sweep by calling list_ad_accounts, then using get_ad_account on each one. This builds a comprehensive report of all accounts and their associated funding instruments for the finance team.

### Checking compliance for promoted content
The operations specialist needs to confirm that every new tweet is live. They use list_promoted_tweets, which quickly lists all active assets, confirming correct deployment across the platform.

## Benefits

- Instead of manually checking line item performance, you can ask the agent to list line items for a specific account, giving you immediate visibility into which efforts are working.
- You don't have to click through multiple dashboards. You can get detailed advertising analytics using get_analytics just by specifying date ranges and metric groups in your prompt.
- The MCP lets you audit not just campaigns, but also individual ads via list_ads, ensuring every piece of creative is accounted for before scaling up spend.
- Need to know the account status? You can use get_ad_account or list_ad_accounts to check metadata and funding instruments without ever touching the X Ads dashboard.
- It helps keep your content governance tight. Use list_promoted_tweets to quickly verify if a specific creative asset is correctly published and active.

## How It Works

The bottom line is that you talk to your agent, and it talks to X Ads for you, giving you instant answers about your ad performance.

1. First, connect your X Ads access token to the MCP via your preferred client (Claude, Cursor, etc.).
2. Next, instruct your agent to perform an action, like listing all ad accounts or checking campaign performance.
3. Your agent executes the call and returns structured data—like a list of line items or analytics metrics—directly into your conversation.

## Frequently Asked Questions

**How do I list all my X ads accounts using the list_ad_accounts tool?**
You simply ask your agent to 'list all ad accounts.' The agent runs list_ad_accounts and returns a structured list of every account ID you manage, letting you know exactly what's available for auditing.

**Can I get historical performance data using the get_analytics tool?**
Yes. You tell your agent which ad entity (like a campaign or line item) you want to check and specify the date range, and it runs get_analytics for the metrics you need.

**What is the difference between list_campaigns and list_line_items?**
List_campaigns provides a high-level view of your efforts. List_line_items dives deeper, showing the specific ad units that make up those campaigns, giving you more precise control.

**Does this MCP help me check my payments?**
Yes. You can use list_funding_instruments to see exactly what payment methods are tied to your account and get_ad_account for general status checks.

**How is my ad data kept secure when I use the get_ad_account tool?**
Credentials pass through a zero-trust proxy, so your keys aren't ever stored on disk. The entire connection runs within Vinkius’s sandbox environment, ensuring every call maintains an auditable and tamper-proof trail.

**What can list_promoted_tweets help me monitor about my content?**
It lists all promoted tweets for a given account. This lets your agent audit creative assets directly, verifying that the right content is published and currently active on X.

**If I only want details on one ad account, should I use list_ad_accounts or get_ad_account?**
You should use get_ad_account. While listing ads accounts gives you a directory, getting the account details provides specific metadata like its current status and funding instrument information.

**Does list_line_items show me enough detail about my budgets?**
Yes, list_line_items is designed to give detailed visibility into your ad spending structure. It lists the individual line items within an account so you can manage and audit specific budget allocations.

**Where do I find the four credentials I need?**
In the [X Developer Portal](https://developer.x.com/), open your App under your Project. Under **Keys and Tokens**, you will find the **API Key** (Consumer Key) and **API Key Secret** (Consumer Secret). Below that, generate your **Access Token** and **Access Token Secret**. All four are required because the X Ads API uses OAuth 1.0a request signing.

**Do I need Ads API approval from X?**
Yes. The X Ads API is access-gated. You need to apply through the [X Developer Portal](https://developer.x.com/) and receive explicit approval before your credentials will work with Ads endpoints. Standard developer accounts only have access to the general X API.

**Can I pull analytics for a specific date range?**
Yes. The analytics tool accepts start and end dates in ISO 8601 format along with metric groups such as Engagement, Billing, or Video. Just ask your agent something like 'show me engagement metrics for campaign X from June 1 to June 15' and it will build the right query.