# MixLift MCP Setup Guide

**For customers setting up MixLift with Claude Desktop**
**Last updated:** 2026-03-07

This guide walks you through installing MixLift and connecting it to Claude Desktop so you can run marketing mix model analyses by asking Claude questions in plain English.

Total time: 10-15 minutes.

---

## Prerequisites

- A computer running macOS 12+ or Windows 10+
- An internet connection
- A MixLift license key (provided after purchase -- check your email from `noreply@mixlift.io`)
- Claude Desktop installed ([download here](https://claude.ai/download))

---

## Step 1: Install Python 3.11+

MixLift requires Python 3.11 or higher. Check if you already have it:

### macOS

Open **Terminal** (press Cmd+Space, type "Terminal", press Enter) and run:

```bash
python3 --version
```

**If you see `Python 3.11.x` or higher** -- skip to Step 2.

**If you see a lower version or an error:**

Option A (recommended): Install from python.org
1. Go to https://www.python.org/downloads/
2. Download the latest Python 3.12 or 3.13 installer for macOS
3. Open the downloaded `.pkg` file and follow the installer
4. Close and reopen Terminal
5. Run `python3 --version` to confirm

Option B: Using Homebrew (if you have it)
```bash
brew install python@3.12
```

### Windows

Open **Command Prompt** (press Win+R, type `cmd`, press Enter) and run:

```cmd
python --version
```

**If you see `Python 3.11.x` or higher** -- skip to Step 2.

**If you see a lower version or an error:**

1. Go to https://www.python.org/downloads/
2. Download the latest Python 3.12 or 3.13 installer for Windows
3. **IMPORTANT:** On the first installer screen, check the box that says **"Add Python to PATH"**
4. Click "Install Now"
5. Close and reopen Command Prompt
6. Run `python --version` to confirm

---

## Step 2: Install MixLift

### macOS

In Terminal, run:

```bash
pip3 install mixlift
```

If you get a "command not found" error for pip3, try:

```bash
python3 -m pip install mixlift
```

### Windows

In Command Prompt, run:

```cmd
pip install mixlift
```

If you get a "command not found" error for pip, try:

```cmd
python -m pip install mixlift
```

**Verify the installation** by running:

```bash
mixlift-mcp --help
```

You should see usage information. If you get "command not found", see Troubleshooting below.

---

## Step 3: Set Your License Key

Your license key was emailed to you after purchase. It looks like a long string of letters and numbers.

### macOS

Open Terminal and run:

```bash
echo 'export MIXLIFT_LICENSE_KEY="your-license-key-here"' >> ~/.zshrc
source ~/.zshrc
```

Replace `your-license-key-here` with your actual license key (keep the quotes).

To verify it's set:
```bash
echo $MIXLIFT_LICENSE_KEY
```

You should see your license key printed.

### Windows

Option A: Via System Settings
1. Press Win+R, type `sysdm.cpl`, press Enter
2. Click the "Advanced" tab
3. Click "Environment Variables"
4. Under "User variables", click "New"
5. Variable name: `MIXLIFT_LICENSE_KEY`
6. Variable value: `your-license-key-here`
7. Click OK on all dialogs

Option B: Via Command Prompt (temporary, current session only)
```cmd
set MIXLIFT_LICENSE_KEY=your-license-key-here
```

Option C: Via PowerShell (permanent)
```powershell
[Environment]::SetEnvironmentVariable("MIXLIFT_LICENSE_KEY", "your-license-key-here", "User")
```

**After setting the variable, close and reopen any terminal windows** for the change to take effect.

---

## Step 4: Configure Claude Desktop

Claude Desktop needs to know about MixLift. You do this by editing a configuration file.

### macOS

1. Open Terminal and run:
   ```bash
   open ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```
   - If the file opens in a text editor, proceed to step 3.
   - If you get a "file not found" error, create it:
     ```bash
     mkdir -p ~/Library/Application\ Support/Claude
     touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
     open ~/Library/Application\ Support/Claude/claude_desktop_config.json
     ```

2. If the file is empty or doesn't exist yet, paste this entire block:
   ```json
   {
     "mcpServers": {
       "mixlift": {
         "command": "mixlift-mcp"
       }
     }
   }
   ```

3. If the file already has content (other MCP servers), add `"mixlift"` inside the existing `"mcpServers"` block. For example, if you already have another server:
   ```json
   {
     "mcpServers": {
       "some-other-server": {
         "command": "some-command"
       },
       "mixlift": {
         "command": "mixlift-mcp"
       }
     }
   }
   ```
   Note the comma after the previous server's closing brace.

4. Save the file (Cmd+S).

### Windows

1. Open File Explorer and navigate to:
   ```
   %APPDATA%\Claude\
   ```
   (Paste that path into the File Explorer address bar and press Enter.)

2. Open `claude_desktop_config.json` in Notepad or any text editor.
   - If the file doesn't exist, create a new file called `claude_desktop_config.json` in that folder.

3. Add or replace the contents with:
   ```json
   {
     "mcpServers": {
       "mixlift": {
         "command": "mixlift-mcp"
       }
     }
   }
   ```

4. Save the file.

### If `mixlift-mcp` Is Not on Your PATH

Sometimes the `mixlift-mcp` command isn't found by Claude Desktop even though it works in your terminal. In that case, use the full path to Python:

**macOS:**
```json
{
  "mcpServers": {
    "mixlift": {
      "command": "python3",
      "args": ["-m", "mixlift_mcp"]
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "mixlift": {
      "command": "python",
      "args": ["-m", "mixlift_mcp"]
    }
  }
}
```

---

## Step 5: Restart Claude Desktop and Test

1. **Quit Claude Desktop completely:**
   - macOS: Cmd+Q (or right-click the dock icon > Quit)
   - Windows: Right-click the taskbar icon > Close window

2. **Reopen Claude Desktop.**

3. **Verify MixLift is connected:**
   Look for a hammer/tools icon in the Claude Desktop input area. Click it -- you should see `mixlift_analyze` listed as an available tool.

   [Description: The tools icon appears as a small hammer icon near the text input field. When clicked, it shows a dropdown listing available MCP tools. "mixlift_analyze" should appear in this list.]

4. **Run your first analysis:**
   Type this message to Claude:

   > Run mixlift_analyze with no arguments

   Claude will run MixLift on a built-in demo dataset. You should see results within 30-60 seconds, including:
   - A dollar headline showing potential revenue impact
   - ROAS (return on ad spend) per channel
   - Saturation analysis with traffic light indicators
   - Budget optimization recommendations

5. **Run on your own data:**
   Save your marketing CSV somewhere on your computer (e.g., your Desktop), then ask Claude:

   > Run mixlift_analyze on /Users/yourname/Desktop/marketing_data.csv

   On Windows:
   > Run mixlift_analyze on C:\Users\yourname\Desktop\marketing_data.csv

---

## CSV Data Format

Your CSV file should have:

- A `date` column with weekly dates
- One or more columns ending in `_spend` for each ad channel
- A `revenue` (or `sales` or `target`) column

Example:

| date | google_ads_spend | meta_spend | tiktok_spend | revenue |
|------|-----------------|------------|-------------|---------|
| 2025-09-01 | 5243.77 | 5658.76 | 1991.60 | 61475.19 |
| 2025-09-08 | 4237.89 | 7190.88 | 1825.93 | 59907.05 |

Minimum: 26 weeks of data. More data = better model.

---

## Troubleshooting

### "Python not found" or wrong version

**Symptom:** `python3 --version` returns an error or a version below 3.11.

**Fix:**
- Install Python from https://www.python.org/downloads/
- On Windows, make sure you checked "Add Python to PATH" during installation
- After installing, close and reopen your terminal
- If you installed Python but the terminal still shows the old version, restart your computer

### "pip not found" or "pip3 not found"

**Symptom:** Running `pip install mixlift` gives a "command not found" error.

**Fix:**
- Try `python3 -m pip install mixlift` (macOS) or `python -m pip install mixlift` (Windows)
- If that also fails, reinstall Python from python.org (the installer includes pip)
- On macOS, if using Homebrew Python, run `brew install python@3.12` which includes pip

### "mixlift-mcp not found" after pip install

**Symptom:** `pip install mixlift` succeeded, but `mixlift-mcp` command is not found.

**Fix:**
- The `mixlift-mcp` script was installed to a directory not on your PATH.
- Find where pip installs scripts:
  - macOS: Usually `~/.local/bin` or `/usr/local/bin`
  - Windows: Usually `C:\Users\yourname\AppData\Local\Programs\Python\Python3xx\Scripts`
- Add that directory to your PATH, or use the alternate Claude Desktop config that calls `python3 -m mixlift_mcp` directly (see Step 4).

### MixLift doesn't appear in Claude Desktop tools

**Symptom:** After restarting Claude Desktop, you don't see `mixlift_analyze` in the tools list.

**Fixes to try in order:**
1. Quit Claude Desktop completely and reopen it (not just close the window -- fully quit the app)
2. Verify your `claude_desktop_config.json` has valid JSON (no trailing commas, all brackets matched). Paste it into https://jsonlint.com/ to check.
3. Verify `mixlift-mcp` works by running it directly in your terminal. You should see some output (it may error about stdin, which is fine -- it proves the command exists).
4. Try the alternate config with `python3 -m mixlift_mcp` (see Step 4)
5. Check Claude Desktop logs for error messages:
   - macOS: `~/Library/Logs/Claude/`
   - Windows: `%APPDATA%\Claude\logs\`

### "Tool not found" when asking Claude to run MixLift

**Symptom:** Claude says it doesn't have access to mixlift_analyze or doesn't know about MixLift.

**Fixes:**
1. Make sure you're using Claude Desktop (not claude.ai in a browser -- MCP tools only work in the desktop app)
2. Check that the tools icon shows `mixlift_analyze` -- if not, the config isn't loaded (see above)
3. Try being explicit: "Use the mixlift_analyze tool to analyze my data"

### Analysis runs but shows free tier limitations

**Symptom:** Results show percentages instead of dollar amounts, or you're told you've hit the 2 runs/month limit.

**Fix:**
- Your license key is not being picked up.
- Verify the environment variable is set: run `echo $MIXLIFT_LICENSE_KEY` (macOS) or `echo %MIXLIFT_LICENSE_KEY%` (Windows) in your terminal.
- If it's empty, revisit Step 3.
- After setting the variable, you must restart Claude Desktop for it to pick up the new environment variable.
- On macOS: also restart Terminal and re-run `source ~/.zshrc` before restarting Claude Desktop.

### Analysis takes more than 2 minutes

**Symptom:** Claude seems to hang or the analysis is very slow.

**This is normal for large datasets.** MixLift runs Bayesian MCMC sampling which is computationally intensive. Typical runtimes:
- 3-4 channels, 52 weeks: 30-60 seconds
- 6-8 channels, 52 weeks: 60-120 seconds
- 8 channels, 100+ weeks: 2-4 minutes

If it consistently takes longer than 5 minutes, your machine may not have enough CPU/RAM. MixLift works best with at least 8GB of RAM.

### License API connection errors

**Symptom:** Error message about being unable to reach the license server.

**Fix:**
- Check your internet connection
- The license server at api.mixlift.io may be temporarily down. MixLift has a 24-hour cached grace period -- if you've successfully validated in the last 24 hours, it will use the cached result.
- If the issue persists for more than an hour, contact support.

---

## Getting Help

If you're stuck on any step, email your MixLift contact (the person who set you up) or reply to your license key email. We typically respond within a few hours and can jump on a screenshare if needed.
