Skip to content
Back to search

ads-mcp

MCP server for managing ad campaigns across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads. 100+ tools for campaign creation, performance analysis, keyword research, and budget optimization. Works with ChatGPT, Claude, Gemini CLI, Cursor, Codex, and Windsurf.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/amekala--ads-mcp/badge.svg)](/listings/amekala--ads-mcp)

HTML

<a href="/listings/amekala--ads-mcp"><img src="/api/listings/amekala--ads-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "adspirer-marketplace",
  3. "metadata": {
  4. "description": "Adspirer performance marketing plugins for Claude Code and Cowork. Manage ad campaigns across Google Ads, Meta, TikTok, LinkedIn, Amazon, and ChatGPT Ads."
  5. },
  6. "owner": {
  7. "name": "Adspirer"
  8. },
  9. "plugins": [
  10. {
  11. "name": "adspirer-advertising-agent",
  12. "displayName": "Adspirer Advertising Agent",
  13. "source": "./",
  14. "description": "Advertising agent for paid media: ad campaign management for Google Ads, Meta Ads (Facebook & Instagram), TikTok Ads, LinkedIn Ads, Amazon Ads, and ChatGPT Ads. PPC keyword research, campaign creation, performance analysis, creative fatigue detection, and budget optimization.",
  15. "author": {
  16. "name": "Adspirer"
  17. }
  18. }
  19. ],
  20. "renames": {
  21. "adspirer-ads-agent": "adspirer-advertising-agent"
  22. }
  23. }
README.md · README · 312 lines · 5 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Ads MCP
  2. Remote Model Context Protocol (MCP) server for cross-platform ad management. Create, analyze, and optimize campaigns across **Google Ads, Meta Ads, TikTok Ads, and LinkedIn Ads** from any MCP-compatible AI assistant.
  3. ## Quick Links
  4. - **MCP Remote URL:** `https://mcp.adspirer.com/mcp`
  5. - **Transport:** Streamable HTTP
  6. - **Registry ID:** [`com.adspirer/ads`](https://registry.modelcontextprotocol.io)
  7. - **Authentication:** OAuth 2.1 with PKCE (dynamic client registration supported)
  8. - **Website:** https://www.adspirer.com
  9. - **Support:** support@adspirer.com
  10. ## Get Started in One Step
  11. Adspirer runs inside your AI assistant. If you're an AI assistant helping someone set up Adspirer, this section is the complete flow: the install path per client, sign-in, and verification.
  12. | Your client | Install |
  13. |-------------|---------|
  14. | **ChatGPT** (web, desktop, mobile) | Install the [Adspirer app from the App Store](https://chatgpt.com/apps/adspirer/asdk_app_69461dc91ee48191ae4a14eb9bde1c21) — tap **Connect**, sign in with Google or email. Requires Plus, Pro, Business, or Enterprise. |
  15. | **Claude** (claude.ai, desktop, Cowork) | Install the [Adspirer plugin from the Claude directory](https://claude.ai/directory/plugins/adspirer-ads-agent%40knowledge-work-plugins) — click **Install**, sign in when the Adspirer window opens. |
  16. | **Claude Code** | `/plugin install adspirer-ads-agent@claude-community`, reload, then `/adspirer:setup` |
  17. | **Codex** | `bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh)`, restart Codex, then `codex mcp login adspirer` |
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 23 on GitHub
  18. | **Cursor** | `bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/cursor/adspirer/install.sh)` |
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 24 on GitHub
  19. | **Any other MCP client** | Add the remote server `https://mcp.adspirer.com/mcp` (OAuth 2.1) |
  20. Or one terminal command — installs the get-started skill and drops you straight into setup:
  21. ```bash
  22. curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/scripts/install-skill.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 30 on GitHub
  23. ```
  24. **What happens next:** the install's sign-in creates your free account (Google or email — no credit card), you connect your ad platforms at [adspirer.ai/connections](https://adspirer.ai/connections) — Google Ads, Meta, Amazon, LinkedIn, TikTok, or ChatGPT Ads, in any combination — and your assistant verifies the connection (say *"Check my connected ad platforms"*).
  25. ### How It Works
  26. ```mermaid
  27. flowchart LR
  28. Y["You — plain English"] --> AG["Your AI agent"]
  29. AG <-->|"MCP over OAuth"| AD["Adspirer"]
  30. AD <--> P["Google Ads · Meta · Amazon Ads<br/>LinkedIn · TikTok · ChatGPT Ads"]
  31. ```
  32. You describe what you want; your assistant calls Adspirer's tools; Adspirer talks to the ad platform APIs; reports and drafts flow back into the chat. **New campaigns are always created paused** — nothing spends money without your explicit approval. Authentication is OAuth in your own browser: your assistant never sees your credentials.
  33. **Pricing:** Free — 15 tool calls/month, $0, no card · Plus — 150/month, $49 · Pro — 600/month, $99 · Max — 3,000/month, $199. [Full details](https://www.adspirer.com/pricing).
  34. **Full setup guide with pasteable prompts:** [adspirer.com/docs/add-to-your-agent](https://www.adspirer.com/docs/add-to-your-agent)
  35. ## What It Does
  36. - **Strategy-aware execution** — strategic decisions persist to `STRATEGY.md` and guide all future campaign creation, keyword research, and ad copy across sessions and subagents
  37. - **400+ tools** across 6 ad platforms for campaign creation, performance analysis, and optimization
  38. - Plan and validate campaigns using structured prompts
  39. - Research keywords with real CPC data and competitive analysis
  40. - Create Google Ads Search, Performance Max (with search themes + audience signals), **Display** (Standard + Smart), **Demand Gen**, and YouTube campaigns end-to-end
  41. - Launch Meta image / video / carousel / OUTCOME_LEADS campaigns, LinkedIn sponsored content / carousel / lead-gen forms with campaign groups, and TikTok in-feed / Spark Ads / Carousel / App Promotion campaigns
  42. - Analyze performance with actionable optimization recommendations — wasted spend, anomaly detection, audience insights, creative fatigue
  43. - **Raw data mode** (`raw_data=true`) on all 29 performance/analytics tools — JSON-only output for your own attribution, dashboards, or token-efficient pipelines
  44. - Multi-account, multi-platform — agencies can manage many ad accounts per platform from one workspace
  45. - Automation — scheduled briefs, performance monitors, on-demand cross-platform reports across all platforms
  46. ## Platforms & Tools
  47. | Platform | Tools | Capabilities |
  48. |----------|-------|-------------|
  49. | Google Ads | 151 | Search, Performance Max (with search themes + audience signals), Display (Standard + Smart), Demand Gen, YouTube, Shopping, App campaigns; keyword research, performance analysis, wasted-spend, asset management, ad extensions (sitelinks / callouts / structured snippets), bidding strategy management |
  50. | Amazon Ads | 61 | Sponsored Products / Brands / Display campaigns, keywords + negative keywords, product / category targeting, Amazon's own bid / budget / keyword recommendations, search-term reports, ACOS / ROAS performance |
  51. | Meta Ads | 58 | Image / video / carousel / catalog (Advantage+ / DPA) campaigns, OUTCOME_LEADS lead-gen forms, lifetime budgets, granular placements (Feed / Stories / Reels), city-level targeting, custom audiences, custom conversions, app-promotion (AEO) analytics |
  52. | LinkedIn Ads | 54 | Sponsored content (single-image, video, carousel, text), lead-gen forms, campaign groups, 19 targeting facets, audience insights, creative fatigue analysis, conversion tracking, organizations |
  53. | TikTok Ads | 37 | In-feed video / image / Spark Ads / Carousel / App Promotion campaigns, full lifecycle (list / get / pause / resume / update for campaigns, ad groups, ads), analytics (performance, wasted spend, audience insights, creative fatigue, anomaly detection, geo) |
  54. | ChatGPT Ads | 31 | chat_card ads inside ChatGPT responses — one-shot launch (campaign → ad group → image → ad), geo targeting, pause / activate / archive, performance (impressions, clicks, CTR, CPC), conversion tracking (Pixel + Conversions API) |
  55. | **Total** | **400+** | Plus monitoring & automation (scheduled briefs / monitors / reports), Google Analytics 4 and Klaviyo integrations, and account management tools — all available over MCP and as REST endpoints at `api.adspirer.ai` |
  56. ## How to Connect
  57. See [CONNECTING.md](CONNECTING.md) for detailed setup instructions for each platform.
  58. ### Claude (Recommended)
  59. 1. Open **Settings > Connectors > Add custom connector**
  60. 2. Name: **Ads MCP**
  61. 3. URL: `https://mcp.adspirer.com/mcp`
  62. 4. Complete OAuth 2.1 sign-in
  63. 5. Link your ad accounts on first use
  64. ### Claude Code
  65. Install the full Adspirer plugin (agent + skills + commands + MCP server):
  66. 1. Open Claude Code
  67. 2. Run `/plugin marketplace add amekala/ads-mcp`
  68. 3. Run `/plugin install adspirer-advertising-agent`
  69. 4. Run `/mcp` — find the **adspirer** server (e.g. **plugin:adspirer-advertising-agent:adspirer**) and click to authenticate
  70. 5. Run `/adspirer:setup` to pull your campaign data and create your brand workspace
  71. This gives you a brand-aware performance marketing agent with persistent memory, competitive research via web search, campaign creation with ad extensions, and slash commands for common workflows.
  72. Enabling subagent usage does not change this installation flow.
  73. **MCP-only (no plugin):** If you just want the raw MCP tools without the agent:
  74. ```bash
  75. claude mcp add --transport http adspirer https://mcp.adspirer.com/mcp
  76. ```
  77. ### ChatGPT
  78. 1. Open **Settings > Connectors > Add custom connector**
  79. 2. Name: **Ads MCP**
  80. 3. URL: `https://mcp.adspirer.com/mcp`
  81. 4. Follow OAuth 2.1 sign-in flow
  82. ### Cursor
  83. Add to `~/.cursor/mcp.json`:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "adspirer": {
  88. "url": "https://mcp.adspirer.com/mcp"
  89. }
  90. }
  91. }
  92. ```
  93. ### OpenAI Codex
  94. Add to `~/.codex/config.toml`:
  95. ```toml
  96. [mcp_servers.adspirer]
  97. url = "https://mcp.adspirer.com/mcp"
  98. ```
  99. ### Gemini CLI
  100. Install as an extension:
  101. ```bash
  102. gemini extensions install github.com/amekala/ads-mcp
  103. ```
  104. A browser window opens for OAuth authentication on first use. Custom commands available: `/adspirer:setup`, `/adspirer:performance-review`, `/adspirer:wasted-spend`, `/adspirer:write-ad-copy`, `/adspirer:refresh`.
  105. ### OpenClaw
  106. ```bash
  107. openclaw plugins install openclaw-adspirer
  108. openclaw adspirer login
  109. openclaw adspirer connect
  110. ```
  111. Or install from [ClawHub](https://clawhub.ai/amekala/adspirer-ads-agent).
  112. ### Perplexity, Manus, and Other MCP Clients
  113. Adspirer is a standard MCP server — any client that supports MCP connectors with OAuth 2.1 (Perplexity, Manus AI, custom MCP clients) can connect to `https://mcp.adspirer.com/mcp`. Manus also accepts API keys via the Streamable HTTP transport.
  114. ### REST API (no MCP client required)
  115. The same tool surface is exposed as 178 REST endpoints at `https://api.adspirer.ai/api/v1/tools/<tool_name>/execute`. Authenticate with a Personal Access Token (`sk_live_...`) created at [adspirer.ai/keys](https://adspirer.ai/keys). Swagger: `https://api.adspirer.ai/docs`. Full reference: [adspirer.com/docs/api-reference](https://www.adspirer.com/docs/api-reference).
  116. ## Example Prompts
  117. **Keyword Research:**
  118. ```
  119. Research keywords for my emergency plumbing business in Chicago.
  120. Show me high-intent keywords with real CPC data and budget recommendations.
  121. ```
  122. **Performance Analysis:**
  123. ```
  124. Show me campaign performance for the last 30 days across all platforms.
  125. Which campaigns are converting best and what should I optimize?
  126. ```
  127. **Campaign Creation:**
  128. ```
  129. Create a Google Performance Max campaign for luxury watches targeting
  130. New York with a $50/day budget.
  131. ```
  132. **Multi-Platform Strategy:**
  133. ```
  134. I want to advertise my handmade jewelry business across Google and LinkedIn.
  135. Research keywords for Google Ads and create a LinkedIn sponsored content campaign
  136. targeting small business owners.
  137. ```
  138. ## Technical Details
  139. - **Protocol:** MCP 2025-03-26 (with fallback to 2024-11-05)
  140. - **Transport:** Streamable HTTP
  141. - **OAuth:** RFC 8252 (Authorization Code + PKCE) with RFC 7591 (Dynamic Client Registration) and RFC 9728 (Protected Resource Metadata)
  142. - **Tool Annotations:** All tools include MCP safety metadata (`readOnlyHint`, `destructiveHint`)
  143. ## Security
  144. - HTTPS/TLS for all data transmission
  145. - OAuth 2.1 with PKCE for authentication
  146. - Dynamic client registration for CLI tools (Claude Code, Cursor, Codex)
  147. - Encrypted token storage
  148. - No conversation logging -- only tool requests are processed
  149. See [SECURITY.md](SECURITY.md) for vulnerability reporting.
  150. ## Documentation
  151. - [Connecting Guide](CONNECTING.md)
  152. - [Privacy Policy](PRIVACY.md)
  153. - [Terms of Service](TERMS.md)
  154. - [Security](SECURITY.md)
  155. - [Support](SUPPORT.md)
  156. ## Support
  157. - **Email:** support@adspirer.com
  158. - **Issues:** https://github.com/amekala/ads-mcp/issues
  159. - **Website:** https://www.adspirer.com
  160. - **Server Status:** https://mcp.adspirer.com/health
  161. ## Supported Plugins
  162. This repo distributes plugins for 4 AI platforms from a single monorepo:
  163. | Platform | Directory | Skills | Install Method |
  164. |----------|-----------|--------|----------------|
  165. | **Claude Code** | Repo root | 1 generated + 5 slash commands | `/plugin marketplace add` |
  166. | **Claude Tag (@claude)** | Upstream: [anthropics/claude-tag-plugins PR #3](https://github.com/anthropics/claude-tag-plugins/pull/3) | 1 (`adspirer-api`: SKILL + 341-tool catalog + `ads_call.sh`) | Org access bundle (Bearer `sk_live_` key, hosts `api.adspirer.ai` / `mcp.adspirer.com`); `claude plugin install adspirer@claude-tag-plugins` once merged |
  167. | **Cursor** | `plugins/cursor/adspirer/` | 5 generated from templates | `install.sh` (one-command) |
  168. | **Codex** | `plugins/codex/adspirer/` | 5 generated from templates | `install.sh` (one-command) |
  169. | **Gemini CLI** | Repo root | 1 reused + 5 custom commands | `gemini extensions install` |
  170. | **OpenClaw** | `plugins/openclaw/` | 1 standalone (self-contained) | `openclaw plugins install` |
  171. > **Claude Tag submission record (2026-07-05):** the `adspirer` plugin for Claude Tag
  172. > (@claude) was submitted upstream as
  173. > [anthropics/claude-tag-plugins#3](https://github.com/anthropics/claude-tag-plugins/pull/3)
  174. > from the fork branch
  175. > [`amekala/claude-tag-plugins@add-adspirer-plugin`](https://github.com/amekala/claude-tag-plugins/tree/add-adspirer-plugin/adspirer).
  176. > It wraps this repo's REST surface (`POST /api/v1/tools/<tool>/execute` — the same MCP
  177. > server tool layer over plain HTTP) rather than the MCP transport, and was validated
  178. > end-to-end in a live Claude Tag workspace (Slack) before submission.
  179. Skills for Claude Code, Cursor, and Codex are authored once in `shared/skills/` as templates, then compiled into IDE-specific versions by `scripts/sync-skills.sh`.
  180. The performance marketing agent prompt is also authored once in `shared/agents/performance-marketing-agent/PROMPT.md` and compiled into Claude Code, Cursor, and Codex agent files by the same sync script.
  181. OpenClaw uses its own standalone skill. See [Architecture](monorepo-restructure-plan.md) for the full design.
  182. ### Shared Update Wireframe
  183. ```text
  184. Edit once (source of truth)
  185. ├─ shared/skills/adspirer-*/SKILL.md
  186. └─ shared/agents/performance-marketing-agent/PROMPT.md
  187. |
  188. v
  189. ./scripts/sync-skills.sh
  190. |
  191. +--> Claude Code outputs
  192. | ├─ skills/<name>/SKILL.md
  193. | └─ agents/performance-marketing-agent.md
  194. |
  195. +--> Cursor outputs
  196. | ├─ plugins/cursor/adspirer/.cursor/skills/adspirer-*/SKILL.md
  197. | └─ plugins/cursor/adspirer/.cursor/agents/performance-marketing-agent.md
  198. |
  199. +--> Codex outputs
  200. | ├─ plugins/codex/adspirer/skills/adspirer-*/SKILL.md
  201. | └─ plugins/codex/adspirer/agents/performance-marketing-agent.toml
  202. |
  203. +--> Gemini CLI (reuses Claude Code skill)
  204. | ├─ gemini-extension.json
  205. | ├─ GEMINI.md
  206. | └─ commands/adspirer/*.toml
  207. |
  208. └--> OpenClaw (standalone, not generated)
  209. └─ plugins/openclaw/SKILL.md
  210. ```
  211. ### Client Roots and Install Targets
  212. | AI Client | Repo Source Root | Generated/Runtime Root in Repo | User Installation Path/Method |
  213. |----------|------------------|--------------------------------|-------------------------------|
  214. | **Claude Code** | Repo root + `shared/skills/` + `shared/agents/` | `skills/`, `agents/`, `commands/`, `.claude-plugin/` | `/plugin marketplace add amekala/ads-mcp` then `/plugin install adspirer-advertising-agent` |
  215. | **Cursor** | `plugins/cursor/adspirer/` + shared sources | `plugins/cursor/adspirer/.cursor/skills/`, `plugins/cursor/adspirer/.cursor/agents/` | `bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/cursor/adspirer/install.sh)` |
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 285 on GitHub
  216. | **Codex** | `plugins/codex/adspirer/` + shared sources | `plugins/codex/adspirer/skills/`, `plugins/codex/adspirer/agents/` | `bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh)` |
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 286 on GitHub
  217. | **Gemini CLI** | Repo root | `gemini-extension.json`, `GEMINI.md`, `commands/adspirer/` | `gemini extensions install github.com/amekala/ads-mcp` |
  218. | **OpenClaw** | `plugins/openclaw/` | `plugins/openclaw/` (standalone, no sync generation) | `openclaw plugins install openclaw-adspirer` |
  219. ## Developer Guide
  220. If you're contributing to this repo or adding new ad platforms/IDE support:
  221. - [Architecture](monorepo-restructure-plan.md) — Shared skills model, template system, what's done and what's remaining
  222. - [Template Syntax & Sync Workflow](docs/architecture.md) — Variable substitution, conditional blocks, validation checks
  223. - [Adding Ad Platforms](docs/adding-platforms.md) — How to add a new ad platform (e.g., Snapchat, Pinterest, YouTube)
  224. - [Adding IDEs](docs/adding-ides.md) — How to add support for a new IDE (e.g., Windsurf, Cline)
  225. ### Quick reference
  226. ```bash
  227. ./scripts/sync-skills.sh # Generate IDE-specific skills from templates
  228. ./scripts/sync-skills.sh --check # Verify generated files match committed (CI mode)
  229. ./scripts/validate.sh # Run all 62 offline validation checks
  230. ./scripts/validate.sh --live # Also test MCP endpoint connectivity
  231. ```
  232. Never edit files in `plugins/*/skills/`, `skills/`, `agents/`, or `plugins/*/agents/` directly — they will be overwritten by the sync script. Edit templates in `shared/skills/` and shared prompts in `shared/agents/` instead.
  233. ## License
  234. Proprietary -- See [Terms of Service](TERMS.md) for usage terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.