Skip to content

getting-started.md

Latest commit

 

History

History
319 lines (212 loc) · 17.7 KB

getting-started.md

File metadata and controls

319 lines (212 loc) · 17.7 KB
Raw

Getting Started

This guide walks you through running mureo end-to-end. mureo is your local-first AI ad ops crew — pick a mode (what data to use) and a host (where the agent runs), then follow the matching walkthrough.

For a 30-second overview of which combination to pick, jump to Choosing the right combination at the bottom.

Before you start

mureo is installed and started from a terminal (your computer's command app — not inside Claude). Open one:

  • macOS: press ⌘ + Space, type Terminal, press Enter.
  • Windows: open the Start menu, type Terminal (or PowerShell), press Enter.
  • Linux: open your terminal application.

mureo needs Python 3.10 or newer. In the terminal, run:

python3 --version

If it prints Python 3.10.x or higher, you're ready (pip ships with Python). If the command is not found or the version is older than 3.10, install Python from https://www.python.org/downloads/ (the installer includes pip), then close and reopen the terminal. If a later step says pip: command not found, use python3 -m pip in place of pip.

Two ways to set up mureo — pick one.

  • Easiest — do it all from a browser (recommended): in the terminal run just two commands — pip install mureo then mureo configure. That opens a local web UI (bound to 127.0.0.1) where you do everything else on this page by point-and-click — host selection, basic setup, OAuth/credentials, official MCP providers, Demo/BYOD. No further commands.
  • Manual — run the commands yourself: everything below walks you through it one command at a time in the terminal. Use this for scripting/CI or fine-grained control.

Both reach the same result. If you're not sure, use mureo configure.

Modes × Hosts at a glance

Claude Code Claude Desktop chat Cowork (Desktop)
Demo (synthetic data) mureo setup claude-code --skip-auth + mureo demo init --scenario seasonality-trap mureo install-desktop --with-demo seasonality-trap Same as Desktop chat + connect the workspace folder in Cowork
BYOD (your XLSX bundle) mureo setup claude-code --skip-auth + mureo byod import bundle.xlsx mureo install-desktop + mureo byod import bundle.xlsx Same as Desktop chat + connect the workspace folder
Auth (Live API) mureo setup claude-code (interactive OAuth) mureo install-desktop + mureo configure Same as Desktop chat + connect the workspace folder

Host quick reference:

  • Claude Code — full skill suite via /<name>, supports Read / Write / Bash / MCP, runs locally in your terminal/IDE.
  • Claude Desktop chat — natural-language only; no Read / Write / Bash tools, only MCP. Skills are invoked by describing the goal ("run a daily check"), not by typing /<name>.
  • Cowork (Desktop) — same MCP entry as the chat tab, plus sandboxed filesystem access to a folder you connect. Best for non-engineers who want the agent to read and write files visually.

Demo (synthetic scenarios)

mureo ships with four scenarios so you can try the agent end-to-end without any real account: seasonality-trap, halo-effect, hidden-champion, strategy-drift. Each generates STRATEGY.md, STATE.json, and a synthetic ad bundle.

A. Demo in Claude Code (5 min)

pip install mureo
mureo setup claude-code --skip-auth      # MCP + skills + credential guard, no OAuth
mureo demo init --scenario seasonality-trap

Then in Claude Code, in the demo workspace directory:

/daily-check

What you should see: a multi-platform health report based on the scenario's synthetic data, a Goal-progress summary, and (depending on the scenario) flagged anomalies with proposed actions.

To switch scenarios: mureo demo init --scenario halo-effect --force.

B. Demo in Claude Desktop chat (10 min)

pip install mureo
mureo install-desktop --workspace ~/mureo --with-demo seasonality-trap

What this does:

  1. Creates ~/mureo/ and seeds it with the scenario (STRATEGY.md, STATE.json, synthetic XLSX bundle).
  2. Generates a wrapper script at ~/.local/bin/mureo-mcp-wrapper.sh that anchors the MCP server to the workspace.
  3. Registers mureo in ~/Library/Application Support/Claude/claude_desktop_config.json.

Then quit Claude Desktop completely (⌘Q) and re-open it.

In a chat tab:

Run a daily check on my campaigns

Claude picks up the skill from natural language and invokes the mureo_* MCP tools to read STRATEGY/STATE and the demo data.

Skills not appearing in the picker? The slash-command picker only shows skills registered in claude.ai. Until Anthropic Skills marketplace accepts mureo, you can either (a) describe goals in natural language as above, or (b) upload each mureo/_data/skills/<name>/SKILL.md manually via the claude.ai web UI.

C. Demo in Cowork (10 min)

Cowork is Claude Desktop's "agentic" tab — same MCP server as the chat tab, plus filesystem access to a folder you connect.

pip install mureo
mureo install-desktop --workspace ~/mureo-demo --with-demo seasonality-trap

Then restart Claude Desktop and switch to the Cowork tab.

  1. Open the Connectors / folder picker in Cowork.
  2. Connect the ~/mureo-demo folder.
  3. Ask in Cowork: 
    Run a daily check

Cowork can both call MCP tools (via the wrapper) AND read/write files inside ~/mureo-demo directly, giving the agent the richest possible view of the workspace.

Why connect the folder? The mureo_strategy_get / mureo_state_* MCP tools work without it, but Cowork's Read/Write tools let the agent inspect raw bundle files, write rollback plans, and so on. Both paths use the same workspace cwd, so updates from either tool are immediately visible to the other.

BYOD — Bring Your Own Data (your XLSX bundles)

BYOD lets you run mureo against a read-only export of your real Google Ads / Meta Ads data without any OAuth flow. Every mutation tool refuses to write, so you cannot accidentally damage a live account.

Step 1 — Get your data file

Platform How to export Time
Google Ads Google Sheet template (Apps Script) → populate Sheet → download .xlsx ~5 min one-time per account
Meta Ads Ads Manager → Reports → Saved Report (mureo template) → 2-click XLSX export ~2 min

Detailed step-by-step:

The exports are independent — you can start with one platform and add the other later. Search Console, GA4, Amazon Ads, and TikTok Ads are not part of BYOD; they require the Live API path. (Amazon Ads is bridged through the official Amazon Ads MCP and has no BYOD bundle by design — see docs/amazon-ads.md.)

BYOD and Demo run on mureo-native only. They are served by mureo's CSV-backed MCP tools; the official platform MCPs (mureo providers add … / the Claude.ai Meta connector) are the Live-API path and cannot read BYOD/demo data. Don't route a platform to the official MCP (or mureo providers add it) if you analyze it via BYOD or the demo — keep mureo-native enabled for it. See docs/byod.md → Compatibility.

Step 2 — Where to put the file

The XLSX itself is just a temporary input — once imported, the data lives under <workspace>/byod/<platform>/ (or the global ~/.mureo/byod/<platform>/ if you are running CLI without install-desktop).

Setup Recommended location for the XLSX
Code (CLI direct) Anywhere — e.g. ~/Downloads/mureo-google-ads.xlsx
Desktop chat Anywhere — but inside ~/mureo/ is convenient because that is the MCP server's workspace
Cowork Inside the connected workspace folder (~/mureo/) so the Cowork sandbox can see it

The filename is arbitrary; you pass the path on import.

Step 3 — Import the file

BYOD import runs from your terminal — run the command below in any shell.

mureo byod import ~/Downloads/mureo-google-ads.xlsx
mureo byod import ~/Downloads/mureo-meta-ads.xlsx     # add Meta later if you skipped it

Where the data lands depends on whether you previously ran mureo install-desktop:

  • Wrapper present (you ran install-desktop): the wrapper exports MUREO_BYOD_DIR=<workspace>/byod at chat time, but the CLI itself uses the legacy default. To target the workspace explicitly when importing: 
    MUREO_BYOD_DIR=$HOME/mureo/byod mureo byod import ~/Downloads/mureo-google-ads.xlsx
  • Wrapper absent (CLI direct, no install-desktop): writes to ~/.mureo/byod/<platform>/ (legacy default).

Switching from demo data to your own data: per-workspace BYOD prevents collisions. mureo install-desktop --workspace ~/mureo-demo --with-demo ... and mureo install-desktop --workspace ~/mureo-real --force give you two independent BYOD stores. See docs/byod.md for migration recipes.

Step 4 — Try a workflow

In Claude Code

/daily-check

In Claude Desktop chat

Run a daily check on my marketing accounts

In Cowork

Same as chat. If you connected the workspace folder, Cowork can also open <workspace>/byod/google_ads/manifest.json to show you what data is loaded.

What works in BYOD

  • Read-only analysis: daily-check, weekly-report, goal-review, search-term-cleanup (analysis), competitive-scan (limited — auction insights are not in the bundle), creative-refresh (suggestions only).
  • Mutation tools (rescue, budget-rebalance, creative-refresh execute, search-term apply) return {"status": "skipped_in_byod_readonly"}. Upgrade to Live API to actually push changes.

Auth (Live API)

Connect mureo directly to Google Ads / Meta Ads APIs. Required for actually executing changes (/rescue, /budget-rebalance, /creative-refresh, mureo rollback apply) and for GA4 / Search Console support. Amazon Ads joins here too, but through a different route: mureo bridges the official Amazon Ads MCP rather than calling an ad API directly — see docs/amazon-ads.md.

Step 1 — Get credentials

Platform What you need
Google Ads Developer Token + OAuth Client ID + Client Secret
Meta Ads Meta for Developers App ID + App Secret (development mode is fine)
Amazon Ads A Login with Amazon (LwA) app: Client ID + (recommended) Refresh Token + Client Secret. See docs/amazon-ads.md
GA4 / Search Console OAuth login (no developer token); the wizard handles this

Approval timing: Google Ads developer-token approval can take 1–3 weeks. Use BYOD in the meantime — switch to Auth once approved.

Credentials land in ~/.mureo/credentials.json (permission 0600). You never need to edit that file by hand — the wizard handles it.

Step 2 — Run the OAuth wizard

Pick the host that matches where you want to run mureo.

A. Auth in Claude Code

pip install mureo
mureo setup claude-code             # interactive OAuth wizard runs as part of setup

The setup command opens a local web wizard at http://127.0.0.1:<random-port>/, where you paste each token / secret in the appropriate field and complete the OAuth flow in the same browser. Skip individual platforms with --no-google-ads / --no-meta-ads if you only want one of them.

Amazon Ads uses a paste-code wizard rather than a redirect-back one — Amazon's consent has no loopback callback for a local tool to listen on. Open mureo configure, scroll the dashboard to Plugin credentials, enter the Login with Amazon Client ID + Client Secret in the Amazon Ads card (or set the AMAZON_ADS_* env vars), then click Open Amazon consent page, approve, and paste the address Amazon redirects you to back into the card. mureo stores both tokens and refreshes the tool list; restart the MCP server afterwards. Full walkthrough: docs/amazon-ads.md.

B. Auth in Claude Desktop chat

pip install mureo
mureo install-desktop --workspace ~/mureo
mureo configure                     # browser UI: OAuth + host setup + providers

Restart Claude Desktop. In a chat tab:

Run a daily check

The MCP server picks up the credentials from ~/.mureo/credentials.json automatically.

C. Auth in Cowork

Same as Desktop chat — Cowork uses the same MCP entry. After install-desktop + auth setup, connect the workspace folder in Cowork (~/mureo) so the agent can also see local files when needed.

D. Auth in OpenAI Codex

pip install mureo
mureo setup codex                   # wires the MCP server + credential-guard hook + skills into ~/.codex
mureo configure                     # browser UI: OAuth + credentials (or do it all here by picking the "OpenAI Codex" host)

Restart Codex — the CLI, IDE extension, and desktop app all share ~/.codex/config.toml, so one setup covers all three. Then run a workflow ("run a daily check", or $daily-check via the /skills picker). The MCP server reads credentials from ~/.mureo/credentials.json automatically.

Step 3 — Verify

mureo auth status
mureo auth check-google             # masked-output verification
mureo auth check-meta

Then run a workflow as in BYOD Step 4 above.

Choosing the right combination

A 30-second decision tree:

  1. Just looking? → Demo in Code or Desktop chat. 5–10 min. Fully reversible (delete the workspace dir).
  2. Have your real account, no developer token? → BYOD. 10–15 min including the export. Read-only, safe.
  3. Have approved developer-token + want execution? → Auth (Live API). 30–60 min first time. Required for /rescue, /budget-rebalance to actually push.
If you... Pick
Want to evaluate mureo on synthetic data Demo + Code
Want to demo to a non-engineer Demo + Desktop chat (no terminal needed after install)
Want richest agent experience for ops Demo + Cowork (folder access)
Have your own account, want analysis only BYOD + Code (or Desktop chat / Cowork)
Need executable mutations Auth + Code (Code is the only host that can run /rescue end-to-end today)

Skill availability by host:

Host Skill triggering Notes
Claude Code /daily-check, /budget-rebalance, … All 20 operational skills + 6 foundation skills available locally
Claude Desktop chat natural language ("run a daily check") Skills must be registered to claude.ai (manual upload or marketplace)
Cowork natural language Same registration story as chat
OpenAI Codex $daily-check / the /skills picker, or natural language Skills install to ~/.codex/skills (CLI / IDE / desktop app share them)

Manual skill upload (claude.ai)

Until Anthropic Skills marketplace lists mureo, Desktop / Cowork users can register skills manually:

  1. Open claude.ai → Skills management page.
  2. For each operational skill, upload the SKILL.md file from mureo/_data/skills/<name>/SKILL.md (20 files: daily-check, tracking-health, budget-rebalance, budget-pacing, search-term-cleanup, creative-refresh, creative-generate, ad-fatigue-check, experiment, lead-form-create, rescue, incident-postmortem, goal-review, weekly-report, monthly-report, competitive-scan, audience-review, onboard, sync-state, learn).
  3. Foundation skills (the _mureo-* ones) are referenced via PREREQUISITE — uploading them is optional but recommended; they reduce the chance the agent misroutes a tool call.
  4. Restart Claude Desktop.

Troubleshooting

"Workspace not found" / [Errno 30] Read-only file system You probably ran mureo install-desktop without --workspace, or Claude Desktop did not pick up your cwd setting. Re-run with an explicit workspace: mureo install-desktop --workspace ~/mureo --force. The wrapper script forces cwd, sidestepping a known Desktop bug.

mureo MCP not appearing in Desktop's Connectors UI Quit Claude Desktop completely (⌘Q) and re-open. The config is only re-read on a full launch.

Demo BYOD data persisting after switching to your real bundle You probably installed both into the same workspace, or both targeted the legacy global ~/.mureo/byod/. Use a separate --workspace for each (e.g. ~/mureo-demo and ~/mureo-real) or mureo byod clear to reset.

Something failed in the mureo configure UI and the message just says it failed Read ~/.mureo/logs/configure.log — every configure run writes there on every platform, and mureo configure prints the path on startup. It holds the cause the UI withholds (an expired token, a rejected account listing, an unwritable credentials file). For more detail, re-run as MUREO_LOG_LEVEL=DEBUG mureo configure. No token or secret is ever written to it. Details: docs/cli.md — Configure log.

/daily-check (or other slash command) does not appear in Code Check ls ~/.claude/skills/ — daily-check should be a directory. If not, re-run mureo setup claude-code. If it appears but the slash picker still shows nothing, restart Claude Code.

For more, see docs/byod.md, docs/authentication.md, and docs/cli.md.