mureo

Website · 日本語

What is mureo?

mureo is a framework for AI agents to autonomously operate ad accounts. Once installed, AI agents (Claude Code, Cursor, Codex, Gemini, etc.) can work across Google Ads, Meta Ads, Search Console, and GA4 -- running campaign diagnostics, search term analysis, budget evaluation, ad validation, and more. Every operation is grounded in your business strategy (STRATEGY.md), so the agent makes decisions based on your persona, USP, goals, and brand voice -- not just raw metrics.

mureo also learns. When you correct the agent's analysis or share an operational insight, /learn saves it to a persistent knowledge base. That knowledge is automatically loaded in every future session, so the agent gets increasingly attuned to your account's specific patterns and makes better decisions over time.

Features

Strategy-driven decisions

Every operation starts from STRATEGY.md -- your persona, USP, brand voice, goals, and operation mode. The agent doesn't just optimize metrics; it optimizes toward your business objectives.

/creative-refresh reads your Persona and USP before drafting a single headline.
/budget-rebalance checks your Operation Mode before shifting a single dollar.
/rescue cross-references your Goals before recommending what to fix first.

Cross-platform analysis

mureo orchestrates across Google Ads, Meta Ads, Search Console, and GA4 in a single workflow:

• /daily-check -- pulls delivery status, ad performance, organic search trends, and site behavior across all platforms, then correlates them into one health report.
• /search-term-cleanup -- compares paid keywords against organic rankings to eliminate wasteful overlap.
• /competitive-scan -- combines auction insights with organic position data for a complete competitive picture.

The agent auto-discovers your configured platforms. Add Meta Ads later? Every command adapts automatically.

Built-in marketing expertise

Campaign diagnostics that pinpoint why ads aren't delivering -- budget constraints, bidding misconfiguration, policy disapprovals, and more. Search term intent classification. Budget efficiency scoring. RSA ad validation and asset auditing. Landing page analysis. Device-level CPA gap detection. The kind of knowledge experienced ad operators carry in their heads -- built into every workflow.

Learnable operational know-how

When you correct the agent or share an operational insight, /learn saves it to a persistent knowledge base. That knowledge is loaded at the start of every future session, so the agent doesn't repeat the same mistakes and applies what it learned to similar situations across your account.

You: "That's not a real CPA spike -- this industry always dips in Golden Week."
Agent: Saved. I'll flag this as seasonal next time.

→ Written to the diagnostic knowledge base.
→ Every future /daily-check and /rescue will factor this in.

Security by design

Marketing accounts are a high-value target. mureo is built with defense-in-depth for AI-driven operations:

• Credential guard — mureo setup claude-code installs a PreToolUse hook that blocks AI agents from reading ~/.mureo/credentials.json, .env, and similar secrets, so a prompt-injection payload cannot exfiltrate tokens via the file-system tools.
• GAQL input validation — every ID, date, date-range constant, and string literal that enters a Google Ads query flows through one whitelist-based surface (mureo/google_ads/_gaql_validator.py), and BETWEEN clauses pattern-match and revalidate their dates instead of passing raw caller input into GAQL.
• Anomaly detection — mureo/analysis/anomaly_detector.py compares current campaign metrics against a median-based baseline from the action log and emits prioritized alerts for zero spend, CPA spikes, and CTR drops, with sample-size gates that suppress single-day noise. Exposed to agents via the analysis.anomalies.check MCP tool; state_file is sandboxed inside the MCP server's CWD so a prompt-injected agent cannot redirect it at an attacker-crafted STATE.json.
• Rollback with allow-list gating — mureo/rollback/ turns agent-authored reversible_params hints into concrete RollbackPlan records. Only operations on an explicit allow-list are planned; destructive verbs (.delete, .remove, .transfer) and unexpected parameter keys are refused, so a compromised agent cannot smuggle a privileged call through the rollback path. mureo rollback list / show let operators preview plans, and the rollback.apply MCP tool executes them by re-dispatching through the same handler used for forward actions so the reversal re-enters the full policy gate (auth, rate limit, validation). Apply requires confirm=true (literal boolean), refuses rollback.* self-recursion, records the reversal as an append-only action_log entry tagged with rollback_of=<index>, and refuses a second apply of the same index.
• Immutable data models — every state object (StateDocument, ActionLogEntry, CampaignSnapshot, Anomaly, RollbackPlan) is a frozen=True dataclass; an agent cannot silently mutate its own record of what happened.
• Local-only credentials — tokens are loaded from ~/.mureo/credentials.json or environment variables and transmitted only to the official ad-platform APIs. mureo itself has no telemetry.

See SECURITY.md for the full threat model and vulnerability reporting process.

Workflow Commands

Getting started

pip install mureo
mureo setup claude-code

# Then in Claude Code:
/onboard          # First time: set up strategy + state
/daily-check      # Daily: check all campaigns
/rescue           # When performance drops

Example: /creative-refresh in action

You: /creative-refresh

Agent reads STRATEGY.md:
  Persona: "Budget-constrained SaaS marketer"
  USP: "AI reduces ad ops workload by 10h/week"
  Brand Voice: "Data-driven, no hype"

Agent discovers platforms from STATE.json:
  → Google Ads + Meta Ads configured

Agent pulls data across platforms and data sources:
  → Creative audit         → 3 underperforming Google Ads assets
  → Landing page analysis  → LP highlights: free trial, ROI improvement
  → Search Console         → "ad automation" has strong organic clicks
  → GA4                    → high bounce rate on pricing page

Agent generates platform-appropriate copy from your strategy:
  Google Ads: "Cut Ad Ops Time by 60% with AI"  ← Persona pain point
  Google Ads: "Free Trial | Ad Automation"       ← LP + organic keyword
  Meta Ads:   "Stop drowning in ad reports..."   ← Brand Voice + social format

Agent validates, then asks for approval:
  "I suggest replacing 3 Google Ads headlines and 2 Meta ads. Here's why..."

You approve → Agent updates each platform.

Analysis & domain knowledge (built-in)

Quick Start

Prerequisites

• Google Ads -- Developer Token and OAuth Client ID / Client Secret
• Meta Ads -- Create an app on Meta for Developers to obtain an App ID / App Secret (development mode is fine)

The mureo auth setup wizard walks you through both.

Browser-based auth wizard (mureo auth setup --web)

Pasting long secrets into a terminal prompt is error-prone. After installation, mureo auth setup --web starts a short-lived local wizard on http://127.0.0.1:<random-port>/ and opens your browser to a local form where you paste the Developer Token / App ID / App Secret (each field has a deep link to Google Cloud Console / Google Ads API Center / Meta for Developers). The OAuth flow completes in the same browser window and the wizard writes ~/.mureo/credentials.json for you.

Claude Code (recommended)

pip install mureo
mureo setup claude-code

This single command handles everything:

1. Google Ads / Meta Ads authentication (OAuth)
2. MCP server configuration for Claude Code
3. Credential guard (blocks AI agents from reading secrets)
4. Workflow commands (/daily-check, /rescue, /learn, etc.)
5. Skills (tool references, strategy guide, evidence-based decisions, diagnostic knowledge)

After setup, run /onboard in Claude Code to get started.

Cursor

pip install mureo
mureo setup cursor

Cursor supports MCP tools but does not support workflow commands or skills.

Codex CLI

pip install mureo
mureo setup codex

Full parity with Claude Code: MCP server, credential guard (PreToolUse hook), workflow commands, and skills are all installed under ~/.codex/. Workflow commands are installed as Codex skills at ~/.codex/skills/<command>/SKILL.md (Codex CLI 0.117.0+ no longer surfaces ~/.codex/prompts/, see openai/codex#15941); invoke them with $daily-check or the /skills picker.

Gemini CLI

pip install mureo
mureo setup gemini

Registers mureo as a Gemini CLI extension at ~/.gemini/extensions/mureo/ with MCP server config and CONTEXT.md as the context file. Gemini CLI does not support PreToolUse hooks or the .md command format mureo bundles, so those layers are not installed.

CLI only (authentication management)

pip install mureo
mureo auth setup
mureo auth status

Docker

Run the mureo MCP server in an isolated container. Useful for:

• Non–Claude Code MCP clients: Cursor, Codex CLI, Gemini CLI, Continue, Cline, Zed, or any custom MCP client.
• CI/CD pipelines: scheduled anomaly checks, rollback dry-runs, weekly reports.
• Multi-tenant / agency ops: isolated credentials per client via separate containers.
• MCP registry health checks (Glama, etc.).

Slash commands (/daily-check, /rescue) and the credential-guard hook are Claude Code–specific UX. For those, use pip install mureo with mureo setup claude-code instead.

Build and run

docker build -t mureo .
docker run --rm -v ~/.mureo:/home/mureo/.mureo mureo

Connect your MCP client by pointing its config at this docker run command.

Authentication

Credentials are loaded from /home/mureo/.mureo/credentials.json inside the container (via bind mount) or from environment variables. Three common patterns:

1. Mounted credentials file — if ~/.mureo/credentials.json already exists on the host (from a prior mureo auth setup, a team-shared vault, or hand-crafted), the bind mount above is enough.

Schema for hand-crafting:

{
  "google_ads": {
    "developer_token": "...",
    "client_id": "...apps.googleusercontent.com",
    "client_secret": "...",
    "refresh_token": "...",
    "login_customer_id": "1234567890"
  },
  "meta_ads": { "access_token": "..." }
}

Required: Google needs developer_token / client_id / client_secret / refresh_token. Meta needs access_token. Search Console reuses the Google OAuth credentials (OAuth app must include the https://www.googleapis.com/auth/webmasters scope).

2. Environment variables — useful for CI/CD where secrets come from a secret manager:

docker run --rm \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=... \
  -e GOOGLE_ADS_CLIENT_ID=... \
  -e GOOGLE_ADS_CLIENT_SECRET=... \
  -e GOOGLE_ADS_REFRESH_TOKEN=... \
  -e GOOGLE_ADS_LOGIN_CUSTOMER_ID=... \
  -e META_ADS_ACCESS_TOKEN=... \
  mureo

Supported: GOOGLE_ADS_{DEVELOPER_TOKEN, CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, LOGIN_CUSTOMER_ID, CUSTOMER_ID}, META_ADS_{ACCESS_TOKEN, APP_ID, APP_SECRET, TOKEN_OBTAINED_AT, ACCOUNT_ID}.

3. Interactive wizard inside Docker — if you don't have OAuth tokens yet and don't want to install mureo on the host:

docker run -it --rm -v ~/.mureo:/home/mureo/.mureo mureo mureo auth setup

Walks you through the OAuth flow in the terminal and writes credentials.json to the mounted volume. Subsequent runs pick it up automatically (pattern 1).

To obtain OAuth tokens outside mureo:

• Google Ads OAuth 2.0 refresh token: https://developers.google.com/google-ads/api/docs/oauth/overview
• Meta long-lived access token: https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived

What gets installed

Skills reference

Connecting GA4 (Google Analytics 4)

mureo's workflow commands can leverage GA4 data (conversion rates, user behavior, landing page performance) when a GA4 MCP server is configured alongside mureo. GA4 data is optional — all commands work without it.

Setup using Google Analytics MCP:

1. Enable the required APIs in your GCP project:

   • Google Analytics Admin API -- click "Enable"
   • Google Analytics Data API -- click "Enable"

2. Install and authenticate:

   pipx install analytics-mcp
   
   gcloud auth application-default login \
     --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform
   

3. Add to ~/.claude/settings.json alongside mureo:

   {
     "mcpServers": {
       "mureo": {
         "command": "python",
         "args": ["-m", "mureo.mcp"]
       },
       "analytics-mcp": {
         "command": "pipx",
         "args": ["run", "analytics-mcp"],
         "env": {
           "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/application_default_credentials.json",
           "GOOGLE_PROJECT_ID": "your-gcp-project-id"
         }
       }
     }
   }
   

Connecting Other MCP Servers

mureo works alongside any MCP server in the same client session. Add them to your settings and workflow commands will incorporate their data when available. See docs/integrations.md for details.

Authentication

Interactive Setup (Recommended)

mureo auth setup

The setup wizard walks you through:

1. Google Ads -- Enter Developer Token + Client ID/Secret, open browser for OAuth, select a Google Ads customer account
2. Meta Ads -- Enter App ID/Secret, open browser for OAuth, obtain a Long-Lived Token, select an ad account. Your Meta App can stay in Development Mode -- no App Review is needed since mureo operates your own ad account. You may see a permission warning for business_management during OAuth; this is safe to accept and required for accessing pages managed through Business Portfolio.
3. MCP config -- Automatically writes .mcp.json (project-level) or ~/.claude/settings.json (global) so Claude Code / Cursor can discover the server

Credentials are saved to ~/.mureo/credentials.json. Search Console reuses the same Google OAuth2 credentials as Google Ads -- no additional authentication is required.

credentials.json

{
  "google_ads": {
    "developer_token": "YOUR_DEVELOPER_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "login_customer_id": "1234567890"
  },
  "meta_ads": {
    "access_token": "YOUR_ACCESS_TOKEN",
    "app_id": "YOUR_APP_ID",
    "app_secret": "YOUR_APP_SECRET"
  }
}

Environment variables (fallback)

Verify your setup:

mureo auth status
mureo auth check-google
mureo auth check-meta

MCP Server

Setup with Claude Code

Project-level (recommended) -- add to .mcp.json in your project root:

{
  "mcpServers": {
    "mureo": {
      "command": "python",
      "args": ["-m", "mureo.mcp"]
    }
  }
}

Global -- add to ~/.claude/settings.json:

{
  "mcpServers": {
    "mureo": {
      "command": "python",
      "args": ["-m", "mureo.mcp"]
    }
  }
}

Tip: mureo auth setup can write this configuration automatically.

Setup with Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "mureo": {
      "command": "python",
      "args": ["-m", "mureo.mcp"]
    }
  }
}

Tool list

Google Ads

Meta Ads

Search Console

Rollback

Analysis

CLI

mureo setup claude-code    # One-command setup for Claude Code
mureo setup cursor         # Setup for Cursor
mureo auth status          # Check authentication status
mureo auth check-google    # Verify Google Ads credentials
mureo auth check-meta      # Verify Meta Ads credentials

Strategy Context

Two local files drive strategy-aware operations. Run /onboard to generate them interactively.

• STRATEGY.md -- Persona, USP, Brand Voice, Goals, Operation Mode. See docs/strategy-context.md.
• STATE.json -- Campaign snapshots, action log. Updated automatically by workflow commands.

Architecture

mureo/
├── __init__.py              # Package root
├── auth.py                  # Credential loading (~/.mureo/credentials.json + env vars + Meta token auto-refresh)
├── auth_setup.py            # Interactive setup wizard (OAuth + MCP config)
├── throttle.py              # Rate limiting (token bucket + rolling hourly cap)
├── _image_validation.py     # Image file validation utilities
├── google_ads/              # Google Ads API client (google-ads SDK wrapper)
│   ├── client.py            # GoogleAdsApiClient (8 Mixin: Ads, Keywords, Analysis, Creative, Diagnostics, Extensions, Media, Monitoring)
│   ├── mappers.py           # Response mapping to structured dicts
│   └── _*.py                # 8 Mixin modules (ads, keywords, analysis, extensions, diagnostics,
│                            #   creative, monitoring, media) + validators + classifiers
├── meta_ads/                # Meta Ads API client (15 Mixins, httpx-based)
│   ├── client.py            # MetaAdsApiClient (Campaigns, AdSets, Ads, Creatives, Audiences, Pixels,
│   │                        #   Insights, Analysis, Catalog, Conversions, Leads, PagePosts, Instagram,
│   │                        #   SplitTest, AdRules)
│   ├── mappers.py           # Response mapping to structured dicts
│   └── _*.py                # 15 Mixin modules (campaigns, ads, creatives, audiences, etc.)
├── search_console/          # Google Search Console API client (reuses Google OAuth2 credentials)
│   └── client.py            # SearchConsoleApiClient
├── analysis/                # Cross-platform analysis utilities
│   └── lp_analyzer.py       # Landing page analysis engine
├── context/                 # File-based context (STRATEGY.md, STATE.json)
│   ├── models.py            # Immutable dataclasses (StrategyEntry, StateDocument)
│   ├── strategy.py          # STRATEGY.md parser / renderer
│   ├── state.py             # STATE.json parser / renderer
│   └── errors.py            # Context-related errors
├── cli/                     # Typer CLI (setup + auth only)
│   ├── main.py              # Entry point (mureo command)
│   ├── setup_cmd.py         # mureo setup claude-code / cursor
│   └── auth_cmd.py          # mureo auth setup / status / check-*
└── mcp/                     # MCP server
    ├── __main__.py                        # python -m mureo.mcp entry point
    ├── server.py                          # MCP server setup (stdio transport)
    ├── _helpers.py                        # Shared handler utilities
    ├── tools_google_ads.py                # Google Ads tool definitions (aggregator)
    ├── _tools_google_ads_*.py             # Tool definition sub-modules
    ├── _handlers_google_ads.py            # Google Ads base handlers
    ├── _handlers_google_ads_extensions.py # Extensions handlers
    ├── _handlers_google_ads_analysis.py   # Analysis handlers
    ├── tools_meta_ads.py                  # Meta Ads tool definitions (aggregator)
    ├── _tools_meta_ads_*.py               # Tool definition sub-modules
    ├── _handlers_meta_ads.py              # Meta Ads base handlers
    ├── _handlers_meta_ads_extended.py     # Extended handlers
    ├── _handlers_meta_ads_other.py        # Other handlers
    ├── tools_search_console.py            # Search Console tool definitions
    └── _handlers_search_console.py        # Search Console handlers

Design principles:

• No database -- all state is either in the ad platform APIs or in local files (STRATEGY.md, STATE.json).
• No LLM dependency -- mureo does not embed an LLM. Inference, planning, and decision-making are the agent's responsibility.
• Immutable data models -- all dataclasses use frozen=True to prevent accidental mutation.
• Credentials stay local -- loaded from ~/.mureo/credentials.json or environment variables. Never sent anywhere except the official ad platform APIs.

Development

git clone https://github.com/logly/mureo.git && cd mureo
pip install -e ".[dev]"
pytest tests/ -v                              # run tests
pytest --cov=mureo --cov-report=term-missing  # with coverage
ruff check mureo/ && black mureo/ && mypy mureo/  # lint & format

Python 3.10+ required. See CONTRIBUTING.md for full development guidelines.

License

Apache License 2.0