Simba MCP Server

Simba is a Bayesian Marketing Mix Modeling (MMM) platform. This Marketing Mix Modeling MCP server lets AI assistants interact with your models directly — upload data, build models, check results, and run budget optimizations through natural language in Claude, Cursor, or Claude Code.

Installation

pip install simba-mcp

Or run directly without installing:

uvx simba-mcp

Related MCP server: Meta Ads MCP

Quick Start

Cursor IDE

Add to your Cursor MCP settings (.cursor/mcp.json in the workspace or global settings):

{
  "mcpServers": {
    "simba": {
      "command": "uvx",
      "args": ["simba-mcp"],
      "env": {
        "SIMBA_API_URL": "https://demo.simba-mmm.com",
        "SIMBA_API_KEY": "simba_sk_..."
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "simba": {
      "command": "uvx",
      "args": ["simba-mcp"],
      "env": {
        "SIMBA_API_URL": "https://demo.simba-mmm.com",
        "SIMBA_API_KEY": "simba_sk_..."
      }
    }
  }
}

Claude API (MCP Connector)

Use the remote Streamable HTTP transport with the Anthropic MCP connector:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    messages=[{"role": "user", "content": "List my Simba models"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://demo.simba-mmm.com/mcp",
            "name": "simba",
            "authorization_token": "simba_sk_...",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "simba"}],
    betas=["mcp-client-2025-11-20"],
)

Available Tools

Example Prompts

Try these with any connected AI assistant:

Explore your models:

"List my Simba models and show me the channel ROI summary for the most recent complete model."

Build a model:

"Upload this CSV data to Simba and create a new MMM model with TV, Search, and Social as media channels. Use 'revenue' as the KPI and 'date' as the date column."

Check progress:

"What's the fitting status of model a1b2c3d4?"

Get results:

"Show me the model diagnostics and channel contributions for model a1b2c3d4."

Optimize budget:

"Run a budget optimization on model a1b2c3d4 with $1M total budget over 12 months. Set TV bounds to 5-40% and Search to 10-50%. Use uniform laydown weights."

Response curves:

"Show me the response curves for model a1b2c3d4. At what spend level does TV hit diminishing returns?"

Scenario planning:

"Get a scenario template for model a1b2c3d4 for the next 12 weeks. Then run a scenario where I increase TV by 20% and cut Search by 10%. What happens to revenue?"

Full workflow:

"I have marketing data I want to analyze. First get the schema so I know what format is needed, then upload my data, create a model, and once it's done show me the ROI by channel."

Agent Skills

The skills/ directory ships workflow skills in the Agent Skills format (SKILL.md per skill) — install them into any skills-aware agent (e.g. Claude Code) alongside this MCP server:

The skills are documentation artifacts — they ride the repo, not the wire protocol.

Gotchas & Tips

Things that commonly trip up both AI agents and humans:

Hosted server: your bearer token IS your login

On HTTP deployments each request is authenticated with the caller's own Authorization: Bearer simba_sk_... token — there is no server-side shared key. If tool calls return "No API key on this request", your MCP client isn't sending the token (check the authorization_token / headers setting in its config).

Channel names are exact-match

Model results are keyed by the channel's activity column name (e.g. "search_activity", "TV_impressions"), not by the channels[].name you passed to create_model. Keys can contain spaces and matching is case-sensitive and space-sensitive — the optimizer and scenario tools use them as dictionary keys.

Always call get_model_results with sections="channel_summary" first to see exact channel keys, then use those verbatim in optimizer/scenario payloads.

Results sections

get_model_results serves these sections (request only what you need via sections=): channel_summary, contributions (KPI/unit space — multiplier not applied), coefficients (per-period per-channel revenue table), params, decay_curves, response_curves, marginal_curves, saturation, mroi_summary (marginal ROI at current spend with 94% HDI; post-#591 fits add the allperiods_unweighted / spendweighted_active convention scalars, and post-#629 fits add a *_mean beside every *_median — the median is displayed, the mean is what reconciles with the marginal-revenue curve), mroi_periods (opt-in only — the per-period marginal ROI series; never in the default payload, request it by name), model_stats, actual_vs_model, long_run_rollup, optimizer, predictions, posterior, financials, model_config. The response's sections_available field is authoritative if the server is newer than these docs.

Models are identified by model_hash

All model endpoints use the string model_hash (e.g. "f835671a25") returned by create_model and list_models.

API-key management is deliberately not exposed

The /api/v1/keys endpoints (create/list/revoke API keys) are session-auth only and have no MCP tools by design: a server holding one key must not be able to mint or revoke keys. Manage keys in the Simba UI (Profile → API Keys).

Optimizer arrays, not scalars

laydown_weights and period_cpm must be objects of arrays, each array having exactly num_periods elements:

// Wrong
"period_cpm": {"TV": 10}

// Correct
"period_cpm": {"TV": [10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10]}

The same channel keys must appear in bounds, laydown_weights, and period_cpm. Bounds values are percentages (0-100) of total_budget, not currency amounts.

Clean NaN from scenario templates

The template from get_scenario_template may contain NaN/null for channels without historical data. Replace them with 0 before passing to run_scenario:

import math
for row in scenario_data:
    for key, val in row.items():
        if val is None or (isinstance(val, float) and math.isnan(val)):
            row[key] = 0

Three endpoints are async

These return 202 and require polling:

Poll every 5-10 seconds. Check the status field for "complete" or "failed".

Data upload requirements

• CSV only (not Excel). Maximum 10 MB (API-enforced).

• Row minimum: check get_data_schema → x-simba-constraints.min_rows; the upload response's warnings field is authoritative. More rows = tighter posteriors (104+ weekly rows recommended).

• Media columns: {channel}_activity and {channel}_spend per channel.

• Use 0 for inactive periods, not blank or NA.

• Large file? Pass csv_path (a local file path) instead of csv_content — the server reads it directly instead of the CSV going through the conversation. Local (stdio) servers only; disabled on HTTP/SSE deployments unless SIMBA_MCP_ALLOW_LOCAL_FILES=1.

Common Errors

Direct API Access

The MCP server wraps the Simba REST API. For scripting, CI/CD, or environments without MCP, you can call the API directly.

When to use MCP vs direct API

Both use the same API keys with the same scopes.

Quick start (Python)

import requests, time

BASE = "https://demo.simba-mmm.com"
HEADERS = {"Authorization": "Bearer simba_sk_..."}

# Upload data
with open("marketing_data.csv", "rb") as f:
    r = requests.post(f"{BASE}/api/v1/ingest",
                      headers={**HEADERS, "Content-Type": "text/csv"},
                      data=f.read(), params={"name": "q1_data"})
file_id = r.json()["id"]

# Create model
r = requests.post(f"{BASE}/api/v1/models", headers=HEADERS, json={
    "data_source": {"uploaded_file_id": file_id},
    "date_column": "date",
    "kpi_column": "revenue",
    "hierarchy_column": "brand",
    "channels": [
        {"name": "TV", "activity_column": "tv_grps", "spend_column": "tv_spend"},
        {"name": "Search", "activity_column": "search_impressions", "spend_column": "search_spend"},
    ],
    "total_media_effect": "Retail",
})
model_hash = r.json()["model_hash"]

# Poll until complete
while True:
    status = requests.get(f"{BASE}/api/v1/models/{model_hash}/status",
                          headers=HEADERS).json()
    if status["status"] in ("complete", "failed"):
        break
    print(f"Fitting... {status.get('progress', '?')}%")
    time.sleep(10)

# Get results
results = requests.get(f"{BASE}/api/v1/models/{model_hash}/results",
                       headers=HEADERS,
                       params={"sections": "channel_summary,model_stats"}).json()
for ch in results["results"]["channel_summary"]:
    print(f"{ch['Channel']}: ROI {ch['ROI']:.1f}")

Quick start (curl)

API_KEY="simba_sk_..."
BASE="https://demo.simba-mmm.com"

# Upload data
curl -X POST "$BASE/api/v1/ingest?name=q1_data" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @marketing_data.csv

# Create model (replace uploaded_file_id with id from upload)
curl -X POST "$BASE/api/v1/models" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_source": {"uploaded_file_id": 1}, "date_column": "date", "kpi_column": "revenue", "hierarchy_column": "brand", "channels": [{"name": "TV", "activity_column": "tv_grps", "spend_column": "tv_spend"}]}'

# Poll status (replace MODEL_HASH)
curl "$BASE/api/v1/models/MODEL_HASH/status" -H "Authorization: Bearer $API_KEY"

# Get results
curl "$BASE/api/v1/models/MODEL_HASH/results?sections=channel_summary,model_stats" \
  -H "Authorization: Bearer $API_KEY"

API Key Setup

The MCP server authenticates with the same API keys used by the Simba REST API. Create a key with the required scopes:

1. Go to Profile > API Keys in the Simba UI

2. Click Create Key

3. Set scopes: ingest, read:models, read:results, create:models, optimize, scenario

4. Copy the key (shown only once)

How the key is supplied depends on where the server runs:

• Local (stdio — Cursor, Claude Code): set it as the SIMBA_API_KEY environment variable in your MCP config (the examples above).

• Hosted (https://demo.simba-mmm.com/mcp): send it as the HTTP Authorization: Bearer header — the authorization_token field in the Claude MCP connector config. Every caller uses their own key (v0.2.2+): the server never shares an identity between callers, a request without a key gets a structured 401 with guidance, and you only ever see your own account's models.

Configuration

Transport Modes

The server supports all MCP transport modes:

# stdio (default) — for Cursor, Claude Code
simba-mcp

# Streamable HTTP — for remote deployment
simba-mcp --transport streamable-http --port 8100

# SSE — legacy transport
simba-mcp --transport sse --port 8100

# Or via uvicorn directly
uvicorn simba_mcp.server:app --host 0.0.0.0 --port 8100

License

MIT