01 · Start here

Connect MixLift to Claude.

Two installation paths. The Cloud path is zero-install — paste a URL into Claude and you're live in under a minute. The Local path is a pip install that keeps your data on your own hardware.

Cloud — MixLift as a Claude connector

Recommended for most users. Included on the Growth plan; nothing to install locally.

1. Open claude.ai in a new tab.
2. Navigate to Settings → Connectors. Scroll to the bottom and click Add custom connector.
3. In the modal, set Name to MixLift.
4. For Remote MCP server URL, paste https://mixlift-cloud.fly.dev/mcp and click Add.
5. Claude will prompt for authentication. Sign in with the email on your MixLift subscription; a one-click magic link will arrive at that address.
6. Return to Claude. Verify the connector is listed under Settings → Connectors.
7. Open a new conversation and ask: "Analyze my marketing data with MixLift."

Local — pip install

For privacy-sensitive pipelines and data teams who prefer to keep every bit of CSV on their own hardware. Identical analysis engine; your data never leaves your machine.

1. Install the Python package:

   pip install mixlift

2. Add MixLift to your Claude Desktop MCP configuration:
   ~/.claude/claude_desktop_config.json

   {
     "mcpServers": {
       "mixlift": {
         "command": "mixlift-mcp"
       }
     }
   }

3. If you're on the Growth plan, add your license key to the environment so platform connectors and unlimited runs are unlocked:

   export MIXLIFT_LICENSE_KEY="MIXLIFT-xxxx-xxxx-xxxx"

4. Restart Claude Desktop. Open a new conversation and ask: "Analyze my marketing data with MixLift."

02 · Start here

Your first analysis.

Once MixLift is connected, the flow is: hand Claude a CSV, ask a budget question, read the output. MixLift does the modeling; Claude translates it.

What your CSV should look like

The simplest input is a weekly CSV with one row per week, one column per paid channel's spend, and one column for revenue. MixLift auto-detects Meta Ads, Google Ads, and TikTok Ads exports; generic CSVs work too.

date,meta_spend,google_spend,tiktok_spend,revenue
2025-01-06,12500,8200,3100,42000
2025-01-13,13100,8400,3200,43500
2025-01-20,12800,8600,3400,45200
...

Ask Claude the question

Open a conversation and paste or attach the CSV. Then ask anything in natural language — MixLift understands budget-oriented prompts out of the box.

• "Where should my next marketing dollar go?"
• "Analyze the attached spend data and tell me which channel is most saturated."
• "If I cut Meta by 20% and move it to TikTok, what happens to revenue over the next 12 weeks?"

Reading the output

The first analysis returns a structured response with a headline, channel scorecard, saturation summary, and three top actions. Here is the channel scorecard from a real demo run:

| Channel         | ROAS  | 90% CI       | Saturated? |
|-----------------|-------|--------------|------------|
| Meta Retarget   | 1.8x  | [1.2, 2.4]   | Yes (91%)  |
| Google Search   | 3.0x  | [2.4, 3.7]   | Moderate   |
| TikTok Prospect | 3.1x  | [2.0, 4.3]   | No (38%)   |
| Email Flows     | 4.6x  | [3.1, 6.2]   | No (22%)   |

Every number has a credible interval — the range the true ROAS lies inside with 90% probability. Channels with wide intervals have less data behind them; treat their point estimates with more caution.

Timing expectations

First-run analysis typically takes 3-8 minutes. MixLift fits a Bayesian model from scratch with 4 MCMC chains; this is not optional but it is only done once per dataset. Subsequent questions on the same data — scenarios, forecasts, different channels to drill into — return in under a second because the fitted model is cached.

03 · Reference

Tool reference.

MixLift exposes fifteen tools to Claude via MCP. You don't invoke them directly — Claude picks the right one based on your question. This reference is for understanding what's happening under the hood and debugging when something doesn't fire as expected.

04 · Reference

Sample workflows.

Three patterns that cover the most common sessions. Each maps to a logical sequence of tool calls — you ask Claude in plain English and it routes through these tools automatically.

05 · Reference

Understanding your results.

MixLift returns three things: ROAS with credible intervals, saturation per channel, and model-fit diagnostics. Here's what each means and how to read it.

ROAS and credible intervals

MixLift reports marginal ROAS — the revenue earned per additional dollar spent at current spend levels. This is different from average ROAS (total revenue divided by total spend). Marginal ROAS accounts for diminishing returns; if you're already saturated on a channel, your marginal ROAS is lower than your average ROAS.

Every ROAS estimate comes with a 90% credible interval. If Meta Retargeting is 1.8x [1.2, 2.4], that means: given your data and the model, there is a 90% probability that the true marginal ROAS is between 1.2x and 2.4x. Narrow intervals mean the channel has enough data; wide intervals mean the channel either hasn't been tested at enough spend levels or is noisy.

Saturation

Each channel's spend-to-revenue relationship is modeled as a curve — near-linear at low spend, flattening at high spend. The saturation percentage is how close you are to the flat part.

• Low saturation (< 40%): increasing spend will likely produce near-linear revenue growth. Prime territory for scale.
• Moderate saturation (40-70%): you still get lift, but each extra dollar returns a bit less than the previous.
• High saturation (> 80%): additional spend mostly reaches users who would have converted anyway. Reallocating to a less-saturated channel is usually the higher-leverage move.

Model quality

Every analysis includes three model-fit diagnostics that tell you how much to trust the rest of the output.

• R-hat: measures whether the Bayesian sampling chains have converged. Values below 1.05 mean the posterior is well-estimated. Above 1.05, MixLift flags the run and recommends adding more data or running with more iterations.
• MAPE on holdout: mean absolute percentage error on the last few weeks of data that the model never saw during fitting. Below 10% is great, 10-20% is acceptable, above 20% usually means the data is thin or the relationship between spend and revenue has shifted mid-period.
• LOO-CV Pareto k: flags individual weeks that had disproportionate influence on the fit. Typically fine; worth checking if you had a flash sale or an ad account outage in the data period.

05 · Theory

Methodology.

This section is for the data scientist your growth leader is about to share this page with. Specific numbers, specific assumptions, specific limitations. No marketing spin.

Attribution vs. incrementality

Meta Pixel and Google Conversions API track which platform received the last click before a conversion — attribution. MixLift's MMM measures the incremental revenue lift from each channel by modeling the relationship between weekly spend and weekly revenue while controlling for seasonality, holidays, and trends — incrementality.

These are fundamentally different questions. Platform attribution is biased toward channels at the ends of the user journey and systematically over-credits (especially post-iOS privacy changes). MMM estimates causal contribution after controlling for confounders. The tradeoff: MMM requires 26+ weeks of data and assumes the spend-revenue relationship is roughly stable; platform attribution works week-to-week but with known biases. For budget decisions, MMM is more reliable; for journey analysis, platform data is richer.

Model structure

MixLift fits a Bayesian MMM via PyMC-Marketing, the open-source library maintained by the PyMC team. The model has four components per channel:

• Geometric adstock — a single decay parameter per channel models lagged effect: spend in week t influences revenue in weeks t, t+1, t+2, ... with geometric decay. Default l_max = 8 weeks.
• Logistic saturation — a two-parameter (slope and max) logistic curve models diminishing returns at higher spend levels.
• Fourier seasonality — six yearly Fourier terms plus a Q4 indicator and per-week US holiday flags. Captures DTC retail seasonality without overfitting.
• Controls — holiday indicators, trend terms, and optional exogenous variables.

MCMC sampling

MixLift samples the posterior with NUTS, the No-U-Turn variant of Hamiltonian Monte Carlo. Default settings:

• 4 chains with 250 draws each — 1,000 posterior samples total, adequate for stable summaries on typical marketer data (52-104 weeks × 3-8 channels).
• target_accept = 0.90 — reduces divergences while maintaining sampling efficiency.
• No fixed random seed — each run samples fresh so convergence diagnostics remain honest. Fixed seeds mask chain-mixing failures.
• R-hat threshold of 1.05 (Gelman-Rubin diagnostic) — runs above this are flagged as unreliable.

Holdout validation

For datasets of 38+ weeks, MixLift runs 3-fold walk-forward cross-validation with a 4-week horizon. For 30-37 weeks, a single held-out 4-week window. Below 30 weeks, holdout is skipped and the run is flagged as exploratory.

The primary trust signal is MAPE on the holdout — mean absolute percentage error on weeks the model never saw during fitting. < 10% is great, 10-20% is acceptable, > 20% usually indicates data quality issues or a structural shift in the data window.

Leave-One-Out Cross-Validation via Pareto-Smoothed Importance Sampling (PSIS-LOO) runs in parallel and flags influential observations. Good fit: no k > 0.7 and p_loo < 40% of data points.

Budget optimization

The optimizer computes marginal ROAS per channel via a 1% finite-difference perturbation at the current spend level. Posterior means (point estimates) drive the optimizer's allocation; the scenario tool uses the full posterior for credible intervals around "what-if" projections.

Limitations — the honest list

MMM makes assumptions. Being upfront about them builds more trust than burying them.

1. Linear-then-saturating response. Step-function changes (new channel launches mid-period, major platform policy changes, brand crises) may fit poorly. If a structural break exists, model the post-break period only.
2. No cross-channel interactions. Meta driving Google branded search, YouTube awareness lifting Meta retargeting — not captured. Top-of-funnel channels may appear lower ROAS; bottom-of-funnel higher. Interpret ROAS comparisons across funnel stages cautiously.
3. Stationarity assumption. The model assumes a roughly stable spend-to-revenue relationship across the data window. If the market changed mid-period, fit on a single regime.
4. Priors dominate on short data. Below 26 weeks, posteriors barely move from PyMC-Marketing's weakly-informative defaults. 26-51 weeks is usable but uncertain; 52+ is production-quality.
5. Optimizer uses point estimates, not full posterior. See the note above.
6. Correlation, not causality. MMM measures correlation after controlling for seasonality and trends; it does not rigorously establish causality the way a geo-lift experiment does. For killing a channel entirely, validate with a holdout test. For 10-20% rebalancing, MMM is typically sufficient.
7. Zero-inflated channels are harder to fit. Channels with many zero-spend weeks or sudden spikes will show up with wider credible intervals and may trigger LOO-CV warnings. Aggregating spiky campaigns into channel bundles usually helps.

Further reading

• PyMC-Marketing documentation — the underlying Bayesian MMM library. Fully open source.
• Jin et al. (2017), Bayesian Methods for Media Mix Modeling with Carryover and Shape Effects — the Google paper that introduced the adstock + saturation approach MixLift inherits.
• Gelman & Rubin (1992, revised 2013) — the R-hat convergence diagnostic.
• Vehtari, Gelman & Gabry (2017), Practical Bayesian model evaluation using leave-one-out cross-validation and WAIC — the LOO-CV + PSIS method.

06 · Help

FAQ & troubleshooting.

How much data do I need?

Hard minimum: 26 weeks. Ideal: 52+ weeks so yearly seasonality is fully identified. 30-51 weeks produces useful analysis with wider credible intervals. Below 26 weeks runs as exploratory only.

My first run is failing. Now what?

In order of likelihood: (1) too few weeks, (2) all-zero columns for a channel that should have been dropped, (3) negative or non-numeric values in spend or revenue columns, (4) a six-plus-week gap of missing dates in the middle of the window. MixLift surfaces the specific failure reason; mixlift_prepare fixes most of them automatically.

Why is my ROAS lower than Meta Ads Manager says?

Almost always because Meta's in-platform attribution counts conversions that would have happened without the ad. MMM controls for baseline revenue (brand, SEO, email, direct) and only credits channels with the incremental lift they drove. A 3-5x gap between platform-reported ROAS and MMM-measured ROAS is normal, especially post-iOS 14.5.

Can I run this on multi-touch data?

MMM is channel-level, not user-level, so it doesn't use multi-touch journey data directly. The output still accounts for channels that influence each other — a channel that drives branded search will show up as having lower direct ROAS in MixLift than in last-click attribution, which is the correct signal.

Is my data secure?

With MixLift Local, data never leaves your machine. With MixLift Cloud, data is encrypted in transit and at rest; the analysis runs in ephemeral compute that is destroyed after the session. We do not train on customer data and do not share it.

Can I refresh an analysis monthly?

Yes. Run mixlift_analyze again with force_refresh=True and updated data. Growth-plan customers can automate this via the platform connectors in mixlift_connect.

07 · Reference

Pricing & tiers.

Short version: Free validates, Growth runs the business.

Full plan comparison and billing FAQ at mixlift.io/pricing.