Repository avatar
AI Tools
v1.3.6
active

adsbeast

io.github.notformal/adsbeast

Ad account audits, analytics, leads and campaign changes that run only from an approved preview.

Documentation

ADS Beast plugins

Connect an AI assistant to ADS Beast, an ad operations platform for agencies and in-house teams. Maintained by Denha Nexus s.r.o.

This repository holds no server code. It holds what an assistant needs to use two hosted MCP servers well: manifests for each client, and workflow skills that tell the assistant which tools to call, in what order, and where to stop and ask.

PluginServerWhat it doesAccount
adsbeasthttps://adsbeast.pro/api/mcp/workspaceYour own workspace: account audits, analytics, campaigns, leads with attribution, alerts, reports, campaign drafts, and changes that run only from a preview you approved.Yes
ad-spec-guardhttps://adsbeast.pro/api/mcpAd platform character limits, creative specs, statistical gates before pausing or scaling, UTM tagging, policy pre-checks.No

Both servers speak MCP over streamable HTTP.

Install

ClientHow
Claude Code/plugin marketplace add notformal/adsbeast-plugins, then /plugin install adsbeast@adsbeast-plugins and /plugin install ad-spec-guard@adsbeast-plugins
Codex CLIcodex plugin marketplace add notformal/adsbeast-plugins, then codex plugin add adsbeast@adsbeast-plugins, then the key: codex mcp add adsbeast --url https://adsbeast.pro/api/mcp/workspace --bearer-token-env-var ADSBEAST_API_KEY and set ADSBEAST_API_KEY (details). Or clone and run adsbeast/clients/codex/install.sh (install.ps1 on Windows)
CursorCopy adsbeast/clients/cursor/mcp.json into ~/.cursor/mcp.json
Gemini CLIgemini extensions install https://github.com/notformal/adsbeast-plugins
WindsurfCopy adsbeast/clients/windsurf/mcp_config.json into ~/.codeium/windsurf/mcp_config.json
Anything elseSee CONNECTING.md

Details, variations and troubleshooting for each client are in CONNECTING.md.

Where this is not available yet: the plugins are not listed in the ChatGPT app directory or in the Claude connector directory. In ChatGPT and in Claude on the web they cannot be added from a catalogue today.

Tool groups of the workspace server

The workspace server serves 187 tools. The table shows the groups the workflows below rely on; the full, current list is the server's own, and tools/list answers without a key.

GroupExamplesWrites
Diagnosticswhoamino
Clientslist_clients, get_client, get_agency_kitno
Campaignslist_campaigns, get_campaign, campaign_dashboard_summary, campaign_analyzeno
Auditsaudit_account, audit_google_ads, audit_meta_ads, audit_wasted_spend, audit_tracking, audit_conversion_goals, audit_campaign_portfoliono
Analyticsanalytics_summary, analytics_compare_periods, analytics_attribution, analytics_forecast, client_goals, client_data_freshnessno
Creativescreative_fatigue_report, meta_ads_learning_phase, google_ads_ad_strengthno
Competitorscompetitor_list, competitor_site_analyze, competitor_search_intel, competitor_ads_researchno
Changes, in two stepsprepare_campaign_pause, prepare_campaign_budget_change, prepare_negative_keywords_add, prepare_campaign_draft_publish, then execute_prepared_change and get_prepared_changeonly from a stored preview
Proposalslist_proposals, reject_proposalreject only
Campaign draftslist_campaign_types, create_campaign_draft, update_campaign_draft, get_campaign_draft, list_campaign_drafts, campaign_draft_publish_checkdrafts only
Leadsget_new_leads, get_lead, lead_pipeline_stats, update_lead, move_lead_stageyes
Conversion outcomeslead_outcome_contract, push_lead_outcomesyes, dry run by default
Alerts, tasks, reportslist_alerts, alerts_unread_count, list_tasks, list_reportsno
Outreachlist_outreach_campaigns, outreach_campaign_check, list_offer_packsno
Webhookslist_webhooks, list_webhook_events, create_webhookyes

Workflow skills

Shipped in adsbeast/skills. Each one starts by checking the connection and ends by saying what it could not check.

SkillUse it for
account-auditA health check of one client's account
wasted-spend-huntCampaigns that spend and do not return
search-terms-negativesTurning a search terms export into negative keywords
campaign-launchBuilding a campaign as a draft: preview, confirm, draft
budget-pacing-checkWhether budgets last the period
weekly-reportA factual weekly status for one client
conversion-tracking-checkWhether results are being counted
lead-pipeline-reviewLead quality, stuck leads, writing outcomes back
creative-fatigue-checkAds the audience has seen too often, on Meta and TikTok
cross-platform-comparisonPlatforms side by side on cost per result and return
competitor-ads-reviewWhat competitors advertise, observed and inferred kept apart
connect-adsbeastA tool answered 401 or 403

In Claude Code, Cursor and Gemini CLI the same workflows are commands, for example /adsbeast:audit and /adsbeast:launch.

Every tool call counts against the monthly allowance of the plan, and whoami reports how many calls are left. The skills are written to ask for what a question needs and no more.

Plans and limits

Every limit the server enforces, per plan. Counters restart on the 1st of the month (UTC). No plan has overage charges or automatic top-ups: at a limit the tool says so and names the reset date. No plan limits ad platforms or campaigns.

PlanTool calls a monthAssistant questions a monthReports a monthClientsPeopleAd accountsPublished landing pages
Free (no card, no time limit)1001531110
Connector2,0003001031no cap3
Starter10,000no capno cap52no cap10
Agency100,000no capno cap5010no cap50
Enterpriseno capno capno cap999100no cap500

Authentication

The workspace server takes a scoped API key, Authorization: Bearer absk_... (X-API-Key also works). An admin creates the key in ADS Beast under API Keys; it is shown once. The key belongs to one organization and carries scopes such as read:campaigns or write:leads. An area the key does not name is unreachable. whoami reports what a key carries.

Sign-in without a key (OAuth 2.1 with PKCE) is implemented on the server, but the discovery documents are not reachable on the production domain yet, so clients that insist on OAuth cannot connect today. Use a key.

Ad Spec Guard needs no authentication.

Security model

  • Read tools and write tools are separate, and every tool declares whether it is read-only or destructive.
  • A change to an ad account runs only from a stored preview. A prepare tool saves exactly what would change and returns a preview id that works once, for 15 minutes. execute_prepared_change takes that id and nothing else, so what runs cannot differ from what was shown. A preview is refused if the campaign changed in the meantime.
  • After that the change waits for a person to approve it in ADS Beast, unless the client's own write policy applies that kind of change automatically. Switching a campaign on always waits for a person.
  • A new campaign is created paused.
  • An integration key cannot approve, roll back, or reach billing, settings and platform credentials. A key bound to a single client can prepare a pause, an enable, a budget change and negative keywords; the audit and analytics tools refuse it.
  • Writing lead outcomes defaults to a dry run.
  • A key can be bound to a single client, and can be revoked at any time under API Keys.
  • Keys are never part of this repository. Every config here reads the key from an environment variable or from the client's own secret store.

What the platform covers

ADS Beast reads campaigns from Google Ads, Meta, TikTok, LinkedIn and Microsoft Advertising accounts that you connect. Its Google Ads API access is at the Basic level; an application for Standard access is pending.

Pricing

Ad Spec Guard is free. The workspace server is part of an ADS Beast account; plans and their MCP allowances are on https://adsbeast.pro/pricing.

Support and legal

Licence

MIT. See LICENSE.