# X Ads (Twitter) MCP

> X Ads (Twitter) MCP lets your AI agent manage every part of your advertising operation through natural conversation. Audit ad accounts, pull detailed performance metrics for specific campaigns or line items, and verify creative assets without opening the ads manager. It's a full audit suite designed to answer complex marketing questions instantly.

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

## Description

Managing paid social campaigns shouldn't feel like clicking through five different dashboards just to get a summary report. This MCP connects your X Ads account directly to your AI client, letting you run an entire advertising operation using simple conversation. Instead of manually pulling reports for spending or engagement, you ask the question—like, 'Show me the CTR difference between retargeting and lookalike audiences last month'—and get a structured answer back immediately.

It gives you full visibility into your ad accounts, letting you list everything from active campaigns to specific ads running under line items. You can analyze performance across custom date ranges, selecting metrics like video views or web conversions on demand. When you connect this MCP via Vinkius, it becomes another powerful tool in your agent's toolkit, giving you access to X Ads data alongside dozens of other services without needing complex API calls.

## Tools

### get_ad_account
Use this to get detailed metadata for a specific X Ads account, confirming its activity status.

### list_ad_accounts
Lists all accessible X (Twitter) Ads accounts, providing their IDs, names, and current statuses.

### list_ads
Retrieves a list of every individual ad, showing which line item and creative asset it belongs to.

### list_campaigns
Lists all campaigns within an X Ads account, including their status, budget, and funding source.

### list_funding_instruments
Provides a list of payment methods and billing sources attached to the ad account for verification.

### list_line_items
Lists all line items across campaigns, which define the targeting rules and bidding strategies used.

### get_analytics
Pulls performance reports for ads, lines, or campaigns over specified date ranges using various metrics (e.g., engagement, billing).

### get_campaign
Fetches the full details of a single campaign when you know its ID.

### get_line_item
Retrieves all specific details for one line item, provided you have its unique ID.

### list_media_creatives
Lists every media asset (images or videos) used in the account to help audit current creative inventory.

### list_promoted_tweets
Verifies which tweets are actively running or paused, listing all promoted content on the account.

### list_tailored_audiences
Lists custom audiences used for retargeting and matching against CRM data.

### list_targeting_criteria
Shows all specific targeting rules that have been applied to a particular line item, requiring both account and line item IDs.

## 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

### Verify account status
Check if an ad account is active and gather its core metadata before running any reports.

### List all campaigns and line items
Retrieve a full structure of every campaign, including details on the targeting and bidding strategy for each line item.

### Pull detailed performance metrics
Generate reports showing daily spending, engagement rates, and conversion numbers across specific ads or campaigns over custom date ranges.

### Audit creative assets
View all media creatives, including images and videos, that are currently running or paused on the account.

### Check billing setup
List attached payment methods and funding instruments to confirm that ad spending is covered.

## Use Cases

### Reviewing Monthly ROI
An Account Manager needs to show a client their overall ad performance for the last quarter. They ask their agent: 'Give me the total web conversion and engagement metrics across all line items from January 1 to March 31.' The agent uses `get_analytics` and delivers a clear, comprehensive breakdown.

### Debugging Campaign Failures
A marketer notices low CTR on one campaign. They ask their agent: 'What are the targeting criteria for line item XYZ?' The agent executes `list_targeting_criteria`, immediately showing if the audience settings were recently changed, solving the mystery fast.

### Pre-Launch Checklist
An Ops Lead is launching a major campaign. They ask their agent to confirm everything: 'List all ad accounts, check funding instruments, and list promoted tweets.' The agent runs `list_ad_accounts` and `list_funding_instruments`, confirming readiness in seconds.

### Auditing Creative Assets
A Growth Lead wants to see if the right creative is running. They ask: 'Which media creatives are active, and are there any promoted tweets we need to review?' The agent runs `list_media_creatives` followed by `list_promoted_tweets`, providing a complete content audit.

## Benefits

- Stop leaving the ads manager. You can now pull complex reports, like comparing line item performance across different campaigns using `get_analytics`, all from your chat interface.
- Instantly audit account health. Use `list_ad_accounts` to see every account ID and status without needing manual logins or API calls.
- Deep-dive into spending details. Check billing setup with `list_funding_instruments` before any major campaign launch to avoid payment delays.
- Manage content inventory easily. Run `list_promoted_tweets` to verify exactly which tweets are running, and use `list_media_creatives` to check the asset library.
- Compare targeting strategies. You can list all criteria using `list_targeting_criteria`, helping you decide if your retargeting efforts need adjusting.

## How It Works

The bottom line is that you treat the entire X Ads platform like a single source of truth within your chat window.

1. Subscribe to this MCP on Vinkius, then input your X Developer Portal credentials (API Key, Secret, Token) into your AI client.
2. Your agent uses the provided authentication to connect and audit the live ad accounts, ensuring all data requests are signed with OAuth 1.0a.
3. You prompt your AI client in natural language—for example, 'What was our engagement metric for Q2?'—and receive an immediate, structured report.

## Frequently Asked Questions

**How do I use X Ads (Twitter) MCP to check my accounts?**
You start by calling `list_ad_accounts`. This tool returns all accessible account IDs and their current statuses, letting you pick the right ID for deeper analysis.

**Can I compare different ad audiences with X Ads (Twitter) MCP?**
Yes. You can use `list_tailored_audiences` to see what custom lists are available for retargeting, which is crucial before running a campaign.

**What metrics does get_analytics support in X Ads (Twitter) MCP?**
The analytics tool supports five core metric groups: Engagement, Billing, Video, Web Conversion, and Mobile Conversion. You specify which group you need when making the request.

**Does the X Ads (Twitter) MCP help me find my ad creative?**
Yes. You can use `list_media_creatives` to list all images and videos, or run `list_promoted_tweets` to see exactly which tweets are currently running.

**Is X Ads (Twitter) MCP secure?**
Yes. The system signs every request with OAuth 1.0a at runtime, and your credentials remain encrypted at rest; they never get exposed to the agent or visible in logs.