Synter MCP Server

An open-source MCP server for running ads with AI agents.

Run ads across 16 ad platforms from any MCP client: Google Ads, Microsoft Ads, Meta, LinkedIn, X, Reddit, TikTok, Snapchat, Pinterest, Spotify, Amazon Ads, Amazon DSP, The Trade Desk, OpenAI Ads, Display & Video 360, and StackAdapt. Destructive tools are flagged so your MCP client asks before running them.

Create campaigns. Adjust budgets. Pause underperformers. Generate creatives. Pull performance data. All through natural conversation.

An open-source Model Context Protocol (MCP) server that lets AI agents read and run your ad accounts, with write tools flagged so your MCP client asks before running them.

Note: Synter-Media-AI/plugin is the canonical installable Claude plugin repo. The .claude-plugin/ copy in this repo is not the install source.

---

Install (hosted, browser sign-in)

The hosted server lives at https://mcp.synterai.com. Add it to your client and sign in through your browser the first time you use it (OAuth with dynamic client registration and PKCE, per the MCP authorization spec). No API key to copy, nothing to install locally.

Signup is self-serve at synterai.com/sign-up. There is no access review: sign up, connect your ad accounts, and your MCP client can start working.

Synter's canonical domain is synterai.com; the hosted MCP endpoint is https://mcp.synterai.com.

⚡ Try in < 60 Seconds with Zero Credentials: Run npx @synterai/mcp-server --demo (or set SYNTER_DEMO=true) to explore campaigns, inspect performance metrics, and simulate mutations with high-fidelity sandbox data. No account or API key required.

Official packages: The only official packages are @synterai/mcp-server, @synterai/sdk-js, PyPI synter, crates.io synter, Maven ai.syntermedia:synter-sdk. @iflow-mcp/* copies are unofficial and outdated.

Cursor: click the badge above, or open cursor://anysphere.cursor-deeplink/mcp/install?name=synter-ads&config=eyJ1cmwiOiJodHRwczovL21jcC5zeW50ZXJhaS5jb20ifQ==

VS Code: click the badge above, or open vscode:mcp/install?%7B%22name%22%3A%22synter-ads%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.synterai.com%22%7D

Claude Code:

claude mcp add --transport http synter-ads https://mcp.synterai.com

Codex:

codex mcp add synter-ads --url https://mcp.synterai.com
codex mcp login synter-ads

Gemini CLI: install this repo as an extension (it ships a gemini-extension.json):

gemini extensions install https://github.com/Synter-Media-AI/mcp-server

Or add it to settings.json:

{"mcpServers":{"synter-ads":{"httpUrl":"https://mcp.synterai.com"}}}

Windsurf: add to ~/.codeium/windsurf/mcp_config.json:

{"mcpServers":{"synter-ads":{"serverUrl":"https://mcp.synterai.com"}}}

Cline:

{"mcpServers":{"synter-ads":{"type":"streamableHttp","url":"https://mcp.synterai.com","disabled":false,"autoApprove":[]}}}

Claude.ai / ChatGPT: add a custom connector with the URL https://mcp.synterai.com and sign in when prompted.

Then start chatting:

"Show me all my Google Ads campaigns"

"Create a search campaign for 'project management software' with a $50/day budget"

"Pause the campaign that's overspending"

---

How Synter Compares

The official Google Ads MCP server is read-only by design: per Google's documentation, it is "strictly read-only" and "cannot modify bids, pause campaigns, or create new assets." Most third-party ad MCP servers cover a single platform or provide raw schema protocols without an execution engine. We built Synter to do both halves of the job, across every major buying channel, with free read-only diagnostics and grounded verification.

	Synter MCP	Official Google Ads MCP	AdCP (Ad Context Protocol)	Pipeboard
Free Read Access	✅ 100% Free ($0.00 / 0 credits)	✅ Free (Google only)	Schema spec only	❌ Paywalled after trial
Write Mutations	✅ Managed paywall (SOLO, SCALE, CUSTOM)	❌ Read-only	❌ Spec only	⚠️ Single-channel proxy
Platform Coverage	16 ad platforms (list below)	Google Ads only	Spec standard only	6 platforms
Grounded Verification	✅ Synter Ångström live readback	❌	❌	❌
Pre-Approved OAuth	✅ 1-click self-serve	Custom cloud setup	None	Basic API keys
AI Creative Generation	✅ Images, video, copy	❌	❌	❌
Audience Sync	✅ Cross-channel custom audiences	❌	❌	❌
Safety	Write tools annotated as destructive	n/a (read-only)	n/a	Varies
Open Source	✅ MIT	✅ Apache 2.0	✅ Apache 2.0	❌ Closed source core

16 ad platforms: Google Ads, Microsoft Ads (Bing), Meta (Facebook and Instagram), LinkedIn Ads, X (Twitter) Ads, Reddit Ads, TikTok Ads, Snapchat Ads, Pinterest Ads, Spotify Ads, Amazon Ads (Sponsored Products, Brands, and Display), Amazon DSP, The Trade Desk, OpenAI Ads (ChatGPT), Display & Video 360, and StackAdapt.

Full campaign creation is available on most of them. Display & Video 360 and StackAdapt support write actions (pause, budget and line-item updates, audience upload) without campaign creation. A few retail media networks are also connected for reporting only.

🔬 Synter Ångström Grounded Output Verification

Never trust an unverified API response. Every mutation and observation in Synter is passed through Synter Ångström, which probes live provider APIs to verify that the effective state, servability (RUNNABLE), delivery status, and constraints match the exact requested intent before reporting back to your agent.

💳 Transparent Pricing: Free Reads & Predictable Writes

• Free Diagnostic Read Tier ($0.00 / 0 credits): Connect your ad accounts and inspect campaigns, pull metrics, and audit tracking completely free. No credit card required.
• Paid Campaign Execution: When you ask your agent to pause campaigns, adjust budgets, create ads, or scale winning angles, execution is billed transparently through Synter subscription tiers:
  • SOLO: $20 / month ($200 / year), includes $20.00 in claimable monthly credits.
  • SCALE: $500 / month ($5,000 / year), includes $500.00 in claimable monthly credits.
  • CUSTOM: Sales-led enterprise contracts with dedicated capacity.

The hosted server at https://mcp.synterai.com exposes the full hosted tool set, including performance pulls for every platform above. The npx package ships typed tools for the most common operations plus run_tool access to the full catalog of 140+ Synter tools.

For registry-style MCP discovery, server.json is the machine-readable source of truth. Keep it aligned with package.json, manifest.json, gemini-extension.json, and the setup examples in this README.

---

🔒 Architecture, Security & Privacy

flowchart TD
    Client["AI Agent / MCP Client<br/>(Claude Desktop, Cursor, VS Code, Windsurf)"]
    
    subgraph LocalTransport["Local or Hosted Transport"]
        Stdio["stdio Transport<br/>npx @synterai/mcp-server<br/>(Optional: SYNTER_READ_ONLY=true)"]
        Streamable["Streamable HTTP<br/>https://mcp.synterai.com<br/>(OAuth 2.1 with PKCE)"]
    end
    
    subgraph SynterGateway["Synter Centralized Gateway (api.synterai.com)"]
        Audit["Append-Only Audit Log<br/>(Tool, caller, latency, cost)"]
        WriteGate{"Write Gate & Blast Radius<br/>(SOLO / SCALE / CUSTOM)"}
        Nango["Credential Custody<br/>(OAuth Tokens AES-256 Encrypted via KMS)"]
    end
    
    subgraph AdNetworks["External Ad Platforms (16+ Networks)"]
        Google["Google Ads"]
        Meta["Meta (FB & IG)"]
        LinkedIn["LinkedIn Ads"]
        MSFT["Microsoft Ads"]
        Other["Reddit, TikTok, X, Amazon, etc."]
    end

    Client --> Stdio & Streamable
    Stdio & Streamable --> SynterGateway
    SynterGateway --> Audit
    SynterGateway --> WriteGate
    WriteGate --> Nango
    Nango --> Google & Meta & LinkedIn & MSFT & Other
    
    classDef client fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef gate fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef platform fill:#334155,stroke:#94a3b8,stroke-width:1px,color:#fff;
    class Client,Stdio,Streamable client;
    class Audit,WriteGate,Nango gate;
    class Google,Meta,LinkedIn,MSFT,Other platform;

Blast-Radius Protection (Bounding the Downside)

Unlike database or analytics MCPs where accidents drop temporary tables, unconstrained ad mutations can incur irreversible ad spend. Synter bounds your blast radius through three layers of defense:

1. Client-Side Read-Only Flag (--read-only / SYNTER_READ_ONLY=true): Pass --read-only or set SYNTER_READ_ONLY=true in your MCP config. Mutating tools (create_, update_, pause_, enable_, sync_audience) are completely unregistered from the tool manifest and blocked locally.
2. Advisory Tool Annotations (readOnlyHint & destructiveHint): Every tool explicitly declares whether it is read-only or destructive per the Model Context Protocol specification, prompting your client before modifying spend or pausing campaigns.
3. Server-Side Write Gates: Even if an agent attempts an unauthorized mutation, Synter's central gateway rejects mutating calls for unverified/cardless callers with 402 PAYMENT_METHOD_REQUIRED.

Data Privacy & Zero Model-Training Guarantee

• Zero Model Training: Customer ad credentials, performance metrics, conversion payloads, and search terms are never used to train or fine-tune models by Synter or its subprocessors.
• Credential Custody: Ad platform OAuth tokens are encrypted at rest using AES-256 with KMS. Tokens are never passed into LLM prompt contexts.
• Immutable Audit Logging: 100% of tool executions are logged with caller identity, IP, tool name, latency, and cost ($0.00 on free diagnosis calls).
• Prompt Injection Resilience: Structured schemas strictly validate all parameters before dispatch, preventing indirect prompt injection from search queries or social comments from altering execution parameters.

---

⚠️ Fair Warning

Your AI agent will be able to:

• Create and launch campaigns that spend real budget once they're live
• Adjust bids that affect how much you pay per click
• Pause campaigns (sometimes that's a good thing)
• Add keywords that change who sees your ads
• Generate creatives and upload them to your accounts

Write tools are annotated as destructive, so MCP clients prompt before running them. But still, maybe don't give this to an agent you just met.

---

Local stdio (npx) / API-key fallback

Use this when your client only speaks stdio, or when you run headless and can't complete a browser sign-in.

⚡ Quick Demo Sandbox Mode (< 60s Evaluation)

Test immediately with realistic mock ad data across Google, Meta, LinkedIn, and more without needing an account or API key:

{
  "mcpServers": {
    "synter-demo": {
      "command": "npx",
      "args": ["-y", "@synterai/mcp-server@latest", "--demo"]
    }
  }
}

Or run directly from your terminal:

npx @synterai/mcp-server --demo

---

1. Get Your API Key (For Live Accounts)

Sign up at synterai.com/sign-up. Your API key is created automatically; you can view it or create more in Developer Settings.

2. Configure Your AI Client

For Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "synter": {
      "command": "npx",
      "args": ["-y", "@synterai/mcp-server@latest", "--read-only"],
      "env": {
        "SYNTER_API_KEY": "syn_your_api_key_here",
        "SYNTER_READ_ONLY": "true"
      }
    }
  }
}

For Cursor: Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "synter-ads": {
      "command": "npx",
      "args": ["-y", "@synterai/mcp-server@latest"],
      "env": {
        "SYNTER_API_KEY": "syn_your_api_key_here"
      }
    }
  }
}

For VS Code / Cline: Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "synter": {
      "command": "npx",
      "args": ["-y", "@synterai/mcp-server@latest"],
      "env": {
        "SYNTER_API_KEY": "syn_your_api_key_here"
      },
      "disabled": false,
      "autoApprove": [
        "pull_google_ads_performance",
        "pull_meta_ads_performance",
        "pull_linkedin_ads_performance",
        "get_spend_reconciliation"
      ]
    }
  }
}

For Windsurf (Codeium): Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "synter": {
      "command": "npx",
      "args": ["-y", "@synterai/mcp-server@latest"],
      "env": {
        "SYNTER_API_KEY": "syn_your_api_key_here"
      }
    }
  }
}

For Amp: Add to .amp/settings.json:

{
  "mcpServers": {
    "synter": {
      "command": "npx",
      "args": ["-y", "@synterai/mcp-server@latest"],
      "env": {
        "SYNTER_API_KEY": "syn_your_api_key_here"
      }
    }
  }
}

HTTP clients that need a header instead of OAuth (n8n, Zapier, scripts, other headless clients):

URL: https://mcp.synterai.com
Header: X-Synter-Key: syn_your_api_key_here

The header is optional; browser OAuth is the default. Works with any MCP client that supports Streamable HTTP transport.

3. Start Using It

Restart your AI client and start chatting.

---

Prefer a full plugin? (Claude Code / Claude Desktop)

This package is the raw MCP server. If you use Claude Code or Claude Desktop, the Synter plugin wraps this same server with ready-made skills (/synter:launch, /synter:audience, /synter:optimize, …), specialized agents, and an approval-before-spend safety hook:

/plugin marketplace add Synter-Media-AI/plugin
/plugin install synter@synter

It also ships a headless Claude Agent SDK runner for automation. See the plugin repo or the Claude Plugin guide. Use this MCP package directly when you want just the tools, or are wiring another client.

---

What Can Your Agent Do?

📊 Campaign Management

Tool	Description
list_campaigns	List campaigns for one ad platform (platform is required)
create_search_campaign	Create a Google Search campaign with keywords and ads
create_display_campaign	Create a Google Display campaign with images
create_pmax_campaign	Create a Performance Max campaign
create_meta_campaign	Create a Facebook/Instagram campaign
create_linkedin_campaign	Create a LinkedIn campaign for B2B
create_reddit_campaign	Create a Reddit campaign
pause_campaign	Pause any campaign
update_campaign_budget	Change daily budget

📈 Performance & Analytics

Tool	Description
get_performance	Get impressions, clicks, spend, conversions, ROAS
get_daily_spend	Daily spend breakdown by platform

🎯 Keywords & Targeting

Tool	Description
add_keywords	Add keywords to a campaign or ad group
add_negative_keywords	Block unwanted search terms

🔄 Conversion Tracking

Tool	Description
create_conversion	Set up a conversion action
list_conversions	List existing conversion actions
diagnose_tracking	Check if tracking is installed correctly

🎨 Creative Generation

Tool	Description
generate_image	AI-generate ad images
generate_video	AI-generate video ads
upload_image	Upload images as ad assets

🔧 Utility

Tool	Description
list_ad_accounts	List all connected ad accounts
run_tool	Run any of 140+ Synter tools directly

Tool names: stdio package vs hosted server

The npx package and the hosted server at https://mcp.synterai.com name a few equivalent tools differently:

stdio (@synterai/mcp-server)	Hosted (https://mcp.synterai.com)
get_performance (with platform)	pull_<platform>_ads_performance, e.g. pull_google_ads_performance, pull_meta_ads_performance
get_daily_spend	No single hosted tool; use pull_<platform>_ads_performance (Google supports segment: "date" for per-day rows)
list_ad_accounts	list_connected_accounts

As of the next hosted release, the hosted server also accepts the stdio names above as aliases, so the same tool calls work against either transport.

---

No Ads Experience? No Problem.

If you've never run ads before, here's what you need to know:

What is a Campaign?

A campaign is like a project folder. It contains your ads, who sees them, and how much you spend.

Campaign: "Q1 Lead Generation"
├── Budget: $50/day
├── Targeting: USA, people searching "project management"
└── Ads: Headlines, descriptions, images

What Platforms Can I Use?

Platform	Best For	Min Budget
Google Ads	People actively searching for your product	$10/day
Meta (Facebook/Instagram)	Visual products, broad audiences	$5/day
LinkedIn	B2B, enterprise, job seekers	$25/day
Reddit	Niche communities, tech-savvy users	$5/day
Microsoft (Bing)	Older demographics, B2B	$10/day
TikTok	Gen Z, entertainment, e-commerce	$20/day

Campaign Types Explained

Search Campaigns: Your ad shows when someone Googles specific keywords.

• Example: Someone searches "best CRM software" → Your ad appears

Display Campaigns: Image ads shown across websites and apps.

• Example: Banner ad on a news site

Performance Max (PMax): Google's AI shows your ads everywhere (Search, YouTube, Display, Gmail, Maps).

• Example: Google figures out the best placements for you

Video Campaigns: Video ads on YouTube and partner sites.

• Example: 15-second ad before a YouTube video

Common Terms

Term	What It Means
Impressions	How many times your ad was shown
Clicks	How many people clicked your ad
CTR	Click-through rate (clicks ÷ impressions × 100)
CPC	Cost per click
Conversions	Desired actions (signups, purchases, etc.)
ROAS	Return on ad spend (revenue ÷ spend)

First Campaign Checklist

Before creating your first campaign, you'll need:

1. ✅ A landing page URL where people will go when they click
2. ✅ An idea of who you want to reach (location, interests)
3. ✅ A daily budget you're comfortable with ($10-50 to start)
4. ✅ Some headlines and descriptions for your ad

Pro tip: Start with a Search campaign on Google. It's the easiest to understand and shows ads to people already looking for what you offer.

---

Example Conversations

Create Your First Campaign

You: Create a Google Search campaign for my SaaS product. Target people searching for "team collaboration software" and "project management tools". Budget is $25/day. Landing page is https://myapp.com/signup

Agent: I'll create a Search campaign with those keywords. What headlines should I use? Here are some suggestions:

• "Team Collaboration Made Simple"
• "Project Management for Modern Teams"
• "Book a Demo Today"

Check Performance

You: How are my campaigns doing this week?

Agent: Here's your performance for the last 7 days:

Campaign	Spend	Clicks	Conversions	ROAS
Brand Search	$142	89	12	4.2x
Competitor Keywords	$98	45	3	1.5x
Display Retargeting	$67	234	8	2.8x

The "Competitor Keywords" campaign is underperforming. Want me to pause it or adjust the targeting?

Add Negative Keywords

You: I'm getting clicks for "project management jobs" but we're not hiring. Block those.

Agent: Added "jobs" as a negative keyword to your campaign. This will stop your ads from showing for any search containing "jobs".

Generate Ad Creative

You: I need a display ad image for a marketing automation product. Dark theme, professional, 1200x628.

Agent: Generating your image...

Created: "Marketing automation dashboard with data visualization on dark background" Asset saved and ready to use in your next Display campaign.

---

Connect Your Ad Accounts

To manage ads on each platform, you'll need to connect your accounts in Synter:

1. Go to synterai.com/settings/credentials
2. Click "Connect" next to each platform
3. Complete the OAuth flow
4. Your agent can now manage that platform

Supported ad platforms (16; ✅ = reporting + full campaign creation, ✏️ = reporting + write actions without campaign creation):

• Google Ads ✅
• Microsoft Ads (Bing) ✅
• Meta (Facebook/Instagram) ✅
• LinkedIn Ads ✅
• X (Twitter) Ads ✅
• Reddit Ads ✅
• TikTok Ads ✅
• Snapchat Ads ✅
• Pinterest Ads ✅
• Spotify Ads ✅
• Amazon Ads ✅
• Amazon DSP ✅
• The Trade Desk ✅
• OpenAI Ads (ChatGPT) ✅
• Display & Video 360 ✏️
• StackAdapt ✏️

A few retail media networks are also connected for reporting only.

---

Advanced: Direct Tool Access

For power users, you can call any of 140+ Synter tools directly:

> Use run_tool to call google_ads_list_audiences

See the full tool list at docs.synterai.com/mcp/tools or ask your agent:

> What tools are available for LinkedIn Ads?

Safety: Confirmations Happen in Your Client

Every write tool, including the universal execute tool, is annotated as destructive, so MCP clients that honor annotations (Claude, Cursor, ChatGPT) ask you before running it. execute runs immediately by default; pass dry_run: true to validate a request without running it. Server-side, Synter checks plan entitlement, account holds, and a payment method on file before campaign writes. It does not add a second approval step, so for anything that spends money, approve only what the account owner wants.

---

Environment Variables

Variable	Required	Description
SYNTER_API_KEY	Yes (stdio)	Your Synter API key, from synterai.com/developer
SYNTER_API_URL	No	API base URL override (default https://synterai.com)
SYNTER_ARTIFACT_API_URL	No	Artifact API override used by stage_audience_artifact (default https://api.synterai.com)