Marketing Agent README

GoMarble for ChatGPT, Codex and Claude

The AI agent for paid media teams, inside ChatGPT, Codex and Claude.
Built by GoMarble.

GoMarble connects your AI assistant to your ad accounts, analytics and store data. It explains what changed and why, and prepares the next move for your approval.

Ask about any account in plain language. GoMarble pulls the data across channels, finds the root cause, and recommends what to do. When you say yes, it makes the change. You can also hand the routine work to agents that watch your accounts on a schedule and report back by email or Slack.

What you can do

The use-case skills follow gomarble.ai/use-cases. Skills load automatically from what you ask; you don't need to name them.

Works with your whole stack

GoMarble supports 80+ integrations. Your assistant can use the GoMarble tools for the ones you connect.

You approve every change

• Analysis never changes anything. Diagnosing, creative analysis, competitor research and reporting are read-only.
• Changes are proposed first. GoMarble validates each change as a dry run, and your assistant shows you each edit, from the current value to the new one. Nothing is applied until you approve, and you can approve some edits and reject others.
• New ads start paused. By default, ads in a campaign built through GoMarble are created paused (TikTok entities start disabled), so nothing spends until you turn them on.
• Agents start as drafts. A new agent doesn't run until you activate it. Agents created from your assistant always ask for approval before making a change. Applying changes automatically can only be set up by a workspace owner or admin in the GoMarble web app.
• Guardrails for teams. On plans with agent governance, you can limit which kinds of changes an agent may make and cap the size of any budget change.

Built for teams

Your assistant works inside your GoMarble team's access rules, so agencies and in-house teams can give everyone access without giving everyone every account.

• Roles: owners and admins reach every account. Members reach only the accounts granted to them.
• View or Act, per account: a member with View can analyze an account; changing it (even proposing a change) needs Act.
• Opt-in write access for AI apps: a connection from ChatGPT, Codex or Claude can read by default. Applying changes on Meta or Google Ads is a permission each person turns on.
• Clear answers when access is missing: your assistant says what's needed and who can grant it, instead of failing silently.

Admins manage roles and access at Settings → Team management, and connections at Settings → Integrations.

What's inside

60 skills. In Claude Code, run any of them by name as /gomarble:<skill>.

Start here

Use cases

Channels

tiktok-ads, linkedin-ads, microsoft-ads, email-marketing (Klaviyo), organic-social (Facebook Pages and Instagram), affiliate-marketing (impact.com), search-console-master-skill, ga4-source-of-truth, shopify-order-discipline.

GoMarble playbooks

The same methodology GoMarble's own agent uses, synced from the GoMarble server:

• Meta: meta-performance-analysis, meta-creative-analysis, meta-depth-of-analysis, meta-guardrails, meta-tool-fundamentals, meta-agent-operations, meta-custom-event-interpretation, meta-create-master-skill
• Google Ads: google-ads-search-analysis, google-ads-search-execution, google-ads-shopping, google-ads-pmax-evaluation, google-ads-pmax-scaling, google-ads-keywordplanner, google-ads-depth-of-analysis, google-ads-guardrails, google-ads-tool-fundamentals, google-ads-create-master-skill
• TikTok: tiktok-create-master-skill

Creative strategy

winning-ads-orchestrator runs the full pipeline from market research to a shoot-ready brief, through competitor-ad-intelligence, creative-research, own-creative-diagnosis, creative-psychology-hooks, winning-pattern-synthesis and ad-brief-generator. winning-ads-engine holds the whole method in one reference.

Business frameworks

gomarble-skills-ecommerce-brands, gomarble-skills-saas-companies, gomarble-skills-creative-strategists.

Morning workflows

Read-only workflows. Each produces analysis and recommendations and never changes the account. In Claude Code, run them as /gomarble:<skill> <account>; elsewhere, ask for them by name.

Plans

A GoMarble account is required. MCP access is included in every plan.

• Free: 1 ad account per connector, 1 seat and 1 read-only agent. No card required.
• Paid plans add more accounts, seats and agents. Plans with write actions add approved changes (launch and edit campaigns, manage keywords, adjust budgets, pause ads) and agents that can make changes.

See gomarble.ai/pricing for current plans, trials and limits.

Install

ChatGPT

Install GoMarble from the ChatGPT plugin directory once it's listed, then sign in when prompted.

Claude Code

/plugin marketplace add https://github.com/gomarble-ai/marketing-agent.git
/plugin install gomarble@gomarble
/reload-plugins

Using the full HTTPS URL avoids SSH-key errors on machines where git rewrites GitHub URLs to SSH.

Claude and Claude Cowork

Install GoMarble from the plugin directory once it's listed. You can also upload the plugin from your organization's plugin settings.

Codex CLI

codex plugin marketplace add https://github.com/gomarble-ai/marketing-agent.git
codex plugin add gomarble@gomarble
codex mcp login gomarble

You can also install it from the Plugins panel in Codex.

One command for both (npm)

npx marketing-agent

This runs the official install commands above on macOS, Linux and Windows, and removes an earlier marketing-agent install if there is one.

Upgrading from marketing-agent

The plugin was renamed from marketing-agent to gomarble. If you installed it before, remove the old one first:

/plugin uninstall marketing-agent@marketing-agent
/plugin marketplace remove marketing-agent

Then install as above. npx marketing-agent does this for you.

Connect your ad accounts

1. The first time your assistant uses GoMarble, you'll be asked to sign in. In ChatGPT and Claude, connect GoMarble when prompted. In Claude Code, run /mcp, pick the GoMarble server, and choose Authenticate. In Codex, run codex mcp login gomarble.
2. Log in at apps.gomarble.ai with your work email.
3. Add your ad accounts and data sources at apps.gomarble.ai/settings/integrations.
4. Come back and ask about your accounts.

Already added GoMarble as a custom connector? If you set it up by hand earlier (for example at https://apps.gomarble.ai/mcp-api/sse), you'll see two GoMarble connectors after installing the plugin. Remove the old custom one in your connector settings and keep the plugin's.

Data and privacy

• What the plugin runs locally: nothing. It has no hooks and no local servers. It contains markdown skills and one connector setting. The scripts/ folder holds maintainer tools that the plugin never runs.
• What it connects to: one remote MCP server, https://apps.gomarble.ai/mcp-api/mcp, over HTTPS. You sign in with OAuth. The plugin stores no credentials.
• What data moves: when your assistant calls a GoMarble tool, GoMarble reads from the ad platforms and data sources you connected in your GoMarble account and returns the results to your assistant. Tool requests and their results pass through GoMarble's servers. Approved changes are applied to your ad accounts by GoMarble through each platform's official API.
• Access control: your assistant can only reach accounts your GoMarble login can reach, at the permission level your workspace grants. You can disconnect data sources in GoMarble, or disconnect the connector in ChatGPT, Codex or Claude, at any time.

GoMarble's privacy policy: gomarble.ai/privacy. Security: gomarble.ai/security.

Repo layout

marketing-agent/
├── .claude-plugin/
│   ├── plugin.json          # Claude manifest (plugin name: gomarble)
│   └── marketplace.json     # marketplace for /plugin marketplace add
├── .codex-plugin/
│   └── plugin.json          # Codex manifest
├── .mcp.json                # GoMarble connector (mcpServers, read by Claude and Codex)
├── skills/                  # 60 skills, read by Claude, ChatGPT and Codex
├── scripts/                 # maintainer tools: skill sync and coverage check
├── installer/install.mjs    # the npx installer
└── README.md

Contributing

GoMarble playbooks come from the server. The Meta, Google Ads, TikTok, GA4, Shopify, Search Console and creative-research skills are synced from GoMarble's server-side skill catalog, the same source the connector's load_skill tool serves. Don't edit them here; change them on the server, then re-sync:

git -C ../mcp-server-sse show origin/main:ads-mcp-server/src/lib/langfuse/langfuse.json > /tmp/langfuse.json
node scripts/sync-server-skills.mjs /tmp/langfuse.json
node scripts/check-coverage.mjs

scripts/skill-map.json maps each server skill to a plugin skill. The sync adds frontmatter, rewrites server paths to plugin skill names, applies scripts/skill-rewrites.json, and adds a short note wherever the server text still assumes GoMarble's own app.

Rewrites keep synced skills usable through the connector. scripts/skill-rewrites.json holds exact find → replace edits for server text that only works inside GoMarble's app, such as its user_input form, in-app-only tools and retired tools. Every find must still match, or the sync fails, so a server wording change can't silently bring back a call to a tool the connector doesn't expose. The better long-term fix is the same wording change in the server skill.

CI (.github/workflows/plugin-ci.yml) runs scripts/validate_plugin.py (OpenAI listing rules and Agent Skills / Codex skill rules), the coverage check, claude plugin validate --strict, the OpenAI ZIP build, an npm pack dry run and a check that the listing links are live.

Every connector tool has a skill. scripts/check-coverage.mjs fails if a tool in scripts/connector-tools.json isn't covered by a skill, or a skill names a tool the connector doesn't expose. Update that list when the connector's tools change.

Other skills (use cases, channels, creative strategy, business frameworks) live here. Keep each SKILL.md under about 3,000 words and put detail in references/.

Raise version in .claude-plugin/plugin.json, .codex-plugin/plugin.json and package.json with every release.

Skills stay provider-neutral. They run in Claude, ChatGPT and Codex, so write "the model" rather than a product name, and keep product names only for product-specific steps such as how to sign in.

OpenAI plugin directory. The OpenAI listing, review test cases and publication settings live in .codex-plugin/plugin.json. Build the upload with npm run pack:openai, which writes dist/gomarble-openai-<version>.zip, and upload it at platform.openai.com/plugins with With MCP.

Support

• Product and docs: gomarble.ai
• Issues and feature requests: github.com/gomarble-ai/marketing-agent/issues
• Account and billing: apps.gomarble.ai

_{© GoMarble. MIT licensed.}