Metadata-Version: 2.4
Name: bluealpha-mmm-builder-mcp
Version: 0.1.3
Summary: MCP server that guides users through building a Marketing Mix Model with Google Meridian
Author: BlueAlpha
License: MIT
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.9.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: xarray>=2023.0
Provides-Extra: meridian
Requires-Dist: google-meridian>=1.4.0; extra == 'meridian'
Description-Content-Type: text/markdown

# BlueAlpha MMM Builder

An MCP server for Claude Desktop that helps you explore whether Marketing Mix Modeling is right for your business, understand your marketing mix, and configure a model — all through conversation.

## Quick Setup (2 minutes)

### 1. Install uv (if you don't have it)

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Add to Claude Desktop

Open Claude Desktop settings, go to **Developer > Edit Config**, and add the `mmm-builder` entry to your `mcpServers`:

```json
{
  "mcpServers": {
    "mmm-builder": {
      "command": "uvx",
      "args": ["bluealpha-mmm-builder-mcp"]
    }
  }
}
```

On Mac, the config file is at: `~/Library/Application Support/Claude/claude_desktop_config.json`

### 3. Restart Claude Desktop

Quit and reopen Claude Desktop. You should see the MMM Builder tools available.

## What It Does

The MMM Builder walks you through 4 phases in natural conversation:

### Phase 1: Is MMM right for me?
- Assess your data readiness (scored 0-100 with specific gaps)
- Estimate the potential savings from better budget allocation
- Understand what data you need

**Try:** *"I spend $100k/month across 4 channels. Is MMM worth it for me?"*

### Phase 2: Data Preparation
- Generate realistic sample data by industry (ecommerce, fintech, healthtech, SaaS, subscription)
- Validate your own CSV against MMM requirements
- Diagnose data quality issues

**Try:** *"I'm an ecommerce brand — show me what MMM data looks like"*
**Or:** *"I have data at ~/Downloads/marketing_data.csv — is it ready for MMM?"*

### Phase 3: Channel Beliefs
This is the core experience. Tell the model what you believe about your channels in plain language:

- *"I think search returns about $4 per dollar and I'm fairly confident"*
- *"Social is maybe half as effective as search"*
- *"TV effects last for weeks, search is immediate"*
- *"We're probably oversaturated on display"*

The tool translates your beliefs into statistical priors (Bayesian distributions) that the model uses as a starting point. Data scientists can also set exact distributions directly.

**Try:** *"Rank my channels: search is best, then social, then display"*

### Phase 4: Model Configuration & Export
- Configure model settings
- Export everything to BlueAlpha for production-grade fitting
- Or fit locally if you have Google Meridian installed

**Try:** *"Export this to BlueAlpha"*

## Sample Prompts to Get Started

| What you want | What to say |
|---|---|
| Learn about MMM | *"What is Marketing Mix Modeling and should I build one?"* |
| Check readiness | *"I have 15 months of weekly data across 5 channels and 10 states. Am I ready?"* |
| See potential value | *"I spend $200k/month on marketing. How much could MMM save me?"* |
| Try with sample data | *"Generate sample data for a fintech company"* |
| Set beliefs | *"I think paid search returns $5 per dollar, social returns $2, and display about $1"* |
| Export to BlueAlpha | *"Package everything up for BlueAlpha to build the production model"* |

## Available Tools (24)

| Phase | Tools | Purpose |
|---|---|---|
| **Readiness** (4) | `assess_mmm_readiness`, `estimate_mmm_value`, `explain_mmm_requirements`, `estimate_model_complexity` | Evaluate fit and potential value |
| **Data Prep** (7) | `list_sample_sectors`, `generate_sample_data`, `validate_data_schema`, `diagnose_data_quality`, `suggest_data_transformations`, `preview_mmm_input_data`, `build_input_data` | Prepare and validate data |
| **Priors** (9) | `set_channel_roi_belief`, `set_channel_cpa_belief`, `rank_channels_by_effectiveness`, `set_adstock_belief`, `set_saturation_belief`, `get_prior_summary`, `reset_channel_priors`, `list_prior_distributions`, `set_custom_prior` | Translate beliefs into model priors |
| **Model** (4) | `configure_model`, `fit_mmm_model`, `export_to_bluealpha`, `get_model_diagnostics` | Configure, fit, or export |

## About BlueAlpha

This MCP Builder gives you a starting point to understand your marketing mix. BlueAlpha deploys and maintains production-grade MMMs with trained data scientists and ML engineers who perform rigorous validation, prior-posterior checks, out-of-sample testing, and ongoing model refreshes.

Think of this tool as your first look — get in touch with the team at [bluealpha.ai](https://bluealpha.ai) to take it to production.

## Troubleshooting

**Server not showing up in Claude Desktop?**
- Make sure you restarted Claude Desktop after editing the config
- Check that `uv` is installed: run `uv --version` in your terminal

**Tools not loading?**
- Check the MCP server logs: `~/Library/Logs/Claude/mcp-server-mmm-builder.log`

**Want to use your own data?**
- Place your CSV somewhere accessible and tell Claude the file path
- The CSV should have columns for: geography, date, KPI (revenue/conversions), and spend per channel
