Simba MCP Server

Simba ist eine Plattform für Bayesianisches Marketing-Mix-Modelling (MMM). Dieser MCP-Server für Marketing-Mix-Modelling ermöglicht es KI-Assistenten, direkt mit Ihren Modellen zu interagieren – Daten hochladen, Modelle erstellen, Ergebnisse prüfen und Budgetoptimierungen über natürliche Sprache in Claude, Cursor oder Claude Code durchführen.

Installation

pip install simba-mcp

Oder direkt ohne Installation ausführen:

uvx simba-mcp

Related MCP server: Meta Ads MCP

Schnellstart

Cursor IDE

Fügen Sie dies zu Ihren Cursor-MCP-Einstellungen hinzu (.cursor/mcp.json im Arbeitsbereich oder globale Einstellungen):

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

Claude Code

Fügen Sie dies zu Ihrer Claude-Code-MCP-Konfiguration hinzu:

{
  "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)

Verwenden Sie den entfernten Streamable-HTTP-Transport mit dem 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"],
)

Verfügbare Tools

Beispiel-Prompts

Probieren Sie diese mit einem beliebigen verbundenen KI-Assistenten aus:

Modelle erkunden:

„Listen Sie meine Simba-Modelle auf und zeigen Sie mir die Kanal-ROI-Zusammenfassung für das neueste abgeschlossene Modell.“

Ein Modell erstellen:

„Laden Sie diese CSV-Daten zu Simba hoch und erstellen Sie ein neues MMM-Modell mit TV, Search und Social als Medienkanälen. Verwenden Sie ‚revenue‘ als KPI und ‚date‘ als Datumsspalte.“

Fortschritt prüfen:

„Wie ist der Fitting-Status von Modell a1b2c3d4?“

Ergebnisse abrufen:

„Zeigen Sie mir die Modelldiagnostik und die Kanalbeiträge für Modell a1b2c3d4.“

Budget optimieren:

„Führen Sie eine Budgetoptimierung für Modell a1b2c3d4 mit einem Gesamtbudget von 1 Mio. $ über 12 Monate durch. Setzen Sie TV-Grenzen auf 5–40 % und Search auf 10–50 %. Verwenden Sie gleichmäßige Laydown-Gewichte.“

Response-Kurven:

„Zeigen Sie mir die Response-Kurven für Modell a1b2c3d4. Ab welchem Ausgabenniveau erreicht TV abnehmende Erträge?“

Szenarioplanung:

„Holen Sie eine Szenariovorlage für Modell a1b2c3d4 für die nächsten 12 Wochen. Führen Sie dann ein Szenario aus, in dem ich TV um 20 % erhöhe und Search um 10 % kürze. Was passiert mit dem Umsatz?“

Vollständiger Workflow:

„Ich habe Marketingdaten, die ich analysieren möchte. Holen Sie zuerst das Schema, damit ich weiß, welches Format benötigt wird, laden Sie dann meine Daten hoch, erstellen Sie ein Modell, und sobald es fertig ist, zeigen Sie mir den ROI nach Kanal.“

Agent-Fähigkeiten

Das Verzeichnis skills/ enthält Workflow-Fähigkeiten im Agent Skills-Format (SKILL.md pro Fähigkeit) – installieren Sie sie in jeden Agenten, der Fähigkeiten unterstützt (z. B. Claude Code), zusammen mit diesem MCP-Server:

Die Fähigkeiten sind Dokumentationsartefakte – sie reisen im Repository, nicht über das Drahtprotokoll.

Stolperfallen & Tipps

Dinge, die sowohl KI-Agenten als auch Menschen häufig ausbremsen:

Gehosteter Server: Ihr Bearer-Token IST Ihr Login

Bei HTTP-Bereitstellungen wird jede Anfrage mit dem eigenen Authorization: Bearer simba_sk_...-Token des Aufrufers authentifiziert – es gibt keinen serverseitigen gemeinsamen Schlüssel. Wenn Tool-Aufrufe "No API key on this request" zurückgeben, sendet Ihr MCP-Client das Token nicht (prüfen Sie die authorization_token-/Header-Einstellung in seiner Konfiguration).

Kanalnamen sind exakte Übereinstimmungen

Modellergebnisse sind nach dem Aktivitätsspaltennamen des Kanals verschlüsselt (z. B. "search_activity", "TV_impressions"), nicht nach dem channels[].name, den Sie an create_model übergeben haben. Schlüssel können Leerzeichen enthalten, und die Übereinstimmung ist groß-/kleinschreibungs- und leerzeichenempfindlich – der Optimizer und die Szenario-Tools verwenden sie als Wörterbuchschlüssel.

Rufen Sie immer zuerst get_model_results mit sections="channel_summary" auf, um die genauen Kanalschlüssel zu sehen, und verwenden Sie diese dann wörtlich in Optimizer-/Szenario-Payloads.

Ergebnisabschnitte

get_model_results liefert diese Abschnitte (fordern Sie nur an, was Sie benötigen, über sections=): channel_summary, contributions (KPI-/Einheitenraum – Multiplikator nicht angewendet), coefficients (Tabelle mit Umsatz pro Periode und Kanal), params, decay_curves, response_curves, marginal_curves, saturation, mroi_summary (marginaler ROI bei aktuellem Spend mit 94 % HDI; Fits nach #591 fügen die allperiods_unweighted-/spendweighted_active-Konventionsskalare hinzu, und Fits nach #629 fügen neben jedem *_median ein *_mean hinzu – der Median wird angezeigt, der Mittelwert ist das, was mit der marginalen Umsatzkurve übereinstimmt), mroi_periods (nur auf Opt-in – die periodenweise marginale ROI-Serie; nie im Standard-Payload, fordern Sie sie namentlich an), model_stats, actual_vs_model, long_run_rollup, optimizer, predictions, posterior, financials, model_config. Das Feld sections_available der Antwort ist maßgeblich, wenn der Server neuer ist als diese Dokumentation.

Modelle werden über model_hash identifiziert

Alle Modell-Endpunkte verwenden den String model_hash (z. B. "f835671a25"), der von create_model und list_models zurückgegeben wird.

API-Schlüsselverwaltung ist bewusst nicht exponiert

Die /api/v1/keys-Endpunkte (API-Schlüssel erstellen/auflisten/widerrufen) sind nur für Sitzungsauthentifizierung gedacht und haben absichtlich keine MCP-Tools: Ein Server, der einen Schlüssel besitzt, darf keine Schlüssel erzeugen oder widerrufen können. Verwalten Sie Schlüssel in der Simba-Oberfläche (Profil → API-Schlüssel).

Optimizer-Arrays, keine Skalare

laydown_weights und period_cpm müssen Objekte aus Arrays sein, wobei jedes Array genau num_periods Elemente hat:

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

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

Dieselben Kanalschlüssel müssen in bounds, laydown_weights und period_cpm erscheinen. Grenzwerte sind Prozentsätze (0–100) des total_budget, keine Währungsbeträge.

NaN aus Szenariovorlagen entfernen

Die Vorlage von get_scenario_template kann NaN/null für Kanäle ohne historische Daten enthalten. Ersetzen Sie sie durch 0, bevor Sie sie an run_scenario übergeben:

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

Drei Endpunkte sind asynchron

Diese geben 202 zurück und erfordern Abfragen:

Fragen Sie alle 5–10 Sekunden ab. Prüfen Sie das Feld status auf "complete" oder "failed".

Anforderungen an den Daten-Upload

• Nur CSV (nicht Excel). Maximum 10 MB (API-erzwungen).

• Zeilenminimum: Prüfen Sie get_data_schema → x-simba-constraints.min_rows; das Feld warnings der Upload-Antwort ist maßgeblich. Mehr Zeilen = engere Posterioris (104+ wöchentliche Zeilen empfohlen).

• Medienspalten: {channel}_activity und {channel}_spend pro Kanal.

• Verwenden Sie 0 für inaktive Perioden, nicht leer oder NA.

• Große Datei? Übergeben Sie csv_path (einen lokalen Dateipfad) anstelle von csv_content – der Server liest die Datei direkt, anstatt dass die CSV durch die Konversation geht. Nur für lokale (stdio) Server; auf HTTP/SSE-Bereitstellungen deaktiviert, außer SIMBA_MCP_ALLOW_LOCAL_FILES=1.

Häufige Fehler

Direkter API-Zugriff

Der MCP-Server kapselt die Simba REST API. Für Skripte, CI/CD oder Umgebungen ohne MCP können Sie die API direkt aufrufen.

Wann MCP vs. direkte API verwenden

Beide verwenden dieselben API-Schlüssel mit denselben Scopes.

Schnellstart (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}")

Schnellstart (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"

Einrichtung des API-Schlüssels

Der MCP-Server authentifiziert sich mit denselben API-Schlüsseln, die auch die Simba REST API verwendet. Erstellen Sie einen Schlüssel mit den erforderlichen Scopes:

1. Gehen Sie in der Simba-Oberfläche zu Profil > API-Schlüssel

2. Klicken Sie auf Schlüssel erstellen

3. Legen Sie die Scopes fest: ingest, read:models, read:results, create:models, optimize, scenario

4. Kopieren Sie den Schlüssel (wird nur einmal angezeigt)

Wie der Schlüssel bereitgestellt wird, hängt davon ab, wo der Server läuft:

• Lokal (stdio — Cursor, Claude Code): Legen Sie ihn als Umgebungsvariable SIMBA_API_KEY in Ihrer MCP-Konfiguration fest (siehe Beispiele oben).

• Gehostet (https://demo.simba-mmm.com/mcp): Senden Sie ihn als HTTP-Header Authorization: Bearer — das Feld authorization_token in der Claude-MCP-Connector-Konfiguration. Jeder Aufrufer verwendet seinen eigenen Schlüssel (v0.2.2+): Der Server teilt niemals eine Identität zwischen Aufrufern, eine Anfrage ohne Schlüssel erhält eine strukturierte 401-Antwort mit Hinweisen, und Sie sehen nur die Modelle Ihres eigenen Kontos.

Konfiguration

Transportmodi

Der Server unterstützt alle MCP-Transportmodi:

# 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

Lizenz

MIT