Simba MCP Server

Simba es una plataforma de modelado de mezcla de marketing (MMM) bayesiano. Este servidor MCP de modelado de mezcla de marketing permite a los asistentes de IA interactuar directamente con tus modelos: subir datos, crear modelos, comprobar resultados y ejecutar optimizaciones de presupuesto mediante lenguaje natural en Claude, Cursor o Claude Code.

Instalación

pip install simba-mcp

O ejecútalo directamente sin instalarlo:

uvx simba-mcp

Related MCP server: Meta Ads MCP

Inicio rápido

Cursor IDE

Añádelo a la configuración MCP de Cursor (.cursor/mcp.json en el espacio de trabajo o en la configuración global):

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

Claude Code

Añádelo a la configuración MCP de Claude Code:

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

API de Claude (conector MCP)

Usa el transporte remoto Streamable HTTP con el conector MCP de Anthropic:

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"],
)

Herramientas disponibles

Ejemplos de indicaciones

Prueba estos con cualquier asistente de IA conectado:

Explora tus modelos:

"Lista mis modelos de Simba y muéstrame el resumen de ROI por canal para el modelo completo más reciente."

Crea un modelo:

"Sube estos datos CSV a Simba y crea un nuevo modelo MMM con TV, Search y Social como canales de medios. Usa 'revenue' como KPI y 'date' como columna de fecha."

Comprueba el progreso:

"¿Cuál es el estado de ajuste del modelo a1b2c3d4?"

Obtén resultados:

"Muéstrame los diagnósticos del modelo y las contribuciones por canal para el modelo a1b2c3d4."

Optimiza el presupuesto:

"Ejecuta una optimización de presupuesto en el modelo a1b2c3d4 con un presupuesto total de $1M durante 12 meses. Establece los límites de TV en 5-40% y los de Search en 10-50%. Usa pesos de distribución uniformes."

Curvas de respuesta:

"Muéstrame las curvas de respuesta del modelo a1b2c3d4. ¿En qué nivel de gasto alcanza TV rendimientos decrecientes?"

Planificación de escenarios:

"Obtén una plantilla de escenario para el modelo a1b2c3d4 para las próximas 12 semanas. Luego ejecuta un escenario donde aumento TV en un 20% y reduzco Search en un 10%. ¿Qué sucede con los ingresos?"

Flujo de trabajo completo:

"Tengo datos de marketing que quiero analizar. Primero obtén el esquema para saber qué formato se necesita, luego sube mis datos, crea un modelo y, una vez que esté listo, muéstrame el ROI por canal."

Habilidades del agente

El directorio skills/ incluye habilidades de flujo de trabajo en el formato Agent Skills (SKILL.md por habilidad): instálalas en cualquier agente compatible con habilidades (por ejemplo, Claude Code) junto con este servidor MCP:

Las habilidades son artefactos de documentación: viajan en el repositorio, no en el protocolo de red.

Advertencias y consejos

Cosas que suelen confundir tanto a los agentes de IA como a los humanos:

Servidor alojado: tu token de portador ES tu inicio de sesión

En las implementaciones HTTP, cada solicitud se autentica con el propio token Authorization: Bearer simba_sk_... del llamante; no hay una clave compartida en el servidor. Si las llamadas a herramientas devuelven "No API key on this request", tu cliente MCP no está enviando el token (revisa la configuración de authorization_token / encabezados en su configuración).

Los nombres de canal coinciden exactamente

Los resultados del modelo se indexan por el nombre de la columna de actividad del canal (por ejemplo, "search_activity", "TV_impressions"), no por el channels[].name que pasaste a create_model. Las claves pueden contener espacios y la coincidencia es sensible a mayúsculas y a espacios: el optimizador y las herramientas de escenario las usan como claves de diccionario.

Siempre llama a get_model_results con sections="channel_summary" primero para ver las claves exactas de los canales y luego úsalas textualmente en los payloads del optimizador/escenario.

Secciones de resultados

get_model_results sirve estas secciones (solicita solo lo que necesites mediante sections=): channel_summary, contributions (espacio de KPI/unidad — el multiplicador no se aplica), coefficients (tabla de ingresos por período y por canal), params, decay_curves, response_curves, marginal_curves, saturation, mroi_summary (ROI marginal al gasto actual con HDI del 94%; los ajustes posteriores a #591 añaden los escalares de convención allperiods_unweighted / spendweighted_active, y los ajustes posteriores a #629 añaden un *_mean junto a cada *_median — la mediana se muestra, la media es la que concilia con la curva de ingresos marginales), mroi_periods (solo opt-in — la serie de ROI marginal por período; nunca en el payload predeterminado, solicítala por nombre), model_stats, actual_vs_model, long_run_rollup, optimizer, predictions, posterior, financials, model_config. El campo sections_available de la respuesta es la autoridad si el servidor es más nuevo que estos documentos.

Los modelos se identifican por model_hash

Todos los endpoints de modelos usan la cadena model_hash (por ejemplo, "f835671a25") devuelta por create_model y list_models.

La gestión de claves API está deliberadamente no expuesta

Los endpoints /api/v1/keys (crear/listar/revocar claves API) son solo de autenticación de sesión y no tienen herramientas MCP por diseño: un servidor que posee una clave no debe poder crear ni revocar claves. Gestiona las claves en la interfaz de Simba (Perfil → Claves API).

Matrices del optimizador, no escalares

laydown_weights y period_cpm deben ser objetos de matrices, cada matriz con exactamente num_periods elementos:

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

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

Las mismas claves de canal deben aparecer en bounds, laydown_weights y period_cpm. Los valores de bounds son porcentajes (0-100) del total_budget, no cantidades monetarias.

Limpia los NaN de las plantillas de escenario

La plantilla de get_scenario_template puede contener NaN/null para canales sin datos históricos. Reemplázalos con 0 antes de pasarlos a 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

Tres endpoints son asíncronos

Estos devuelven 202 y requieren consulta:

Consulta cada 5-10 segundos. Comprueba el campo status para "complete" o "failed".

Requisitos de subida de datos

• Solo CSV (no Excel). Máximo 10 MB (impuesto por la API).

• Mínimo de filas: consulta get_data_schema → x-simba-constraints.min_rows; el campo warnings de la respuesta de subida es la autoridad. Más filas = posteriores más ajustados (se recomiendan 104+ filas semanales).

• Columnas de medios: {channel}_activity y {channel}_spend por canal.

• Usa 0 para períodos inactivos, no en blanco o NA.

• ¿Archivo grande? Pasa csv_path (una ruta de archivo local) en lugar de csv_content — el servidor lo lee directamente en lugar de que el CSV pase por la conversación. Solo servidores locales (stdio); deshabilitado en implementaciones HTTP/SSE a menos que SIMBA_MCP_ALLOW_LOCAL_FILES=1.

Errores comunes

Acceso directo a la API

El servidor MCP envuelve la API REST de Simba. Para scripting, CI/CD o entornos sin MCP, puedes llamar a la API directamente.

Cuándo usar MCP vs API directa

Ambos usan las mismas claves de API con los mismos alcances.

Inicio rápido (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}")

Inicio rápido (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"

Configuración de la clave de API

El servidor MCP se autentica con las mismas claves de API utilizadas por la API REST de Simba. Crea una clave con los alcances requeridos:

1. Ve a Perfil > Claves de API en la interfaz de Simba

2. Haz clic en Crear clave

3. Establece los alcances: ingest, read:models, read:results, create:models, optimize, scenario

4. Copia la clave (se muestra solo una vez)

Cómo se suministra la clave depende de dónde se ejecute el servidor:

• Local (stdio — Cursor, Claude Code): configúrala como la variable de entorno SIMBA_API_KEY en tu configuración de MCP (los ejemplos anteriores).

• Alojado (https://demo.simba-mmm.com/mcp): envíala como el encabezado HTTP Authorization: Bearer — el campo authorization_token en la configuración del conector MCP de Claude. Cada llamador usa su propia clave (v0.2.2+): el servidor nunca comparte una identidad entre llamadores, una solicitud sin clave recibe un 401 estructurado con orientación, y solo ves los modelos de tu propia cuenta.

Configuración

Modos de transporte

El servidor admite todos los modos de transporte de MCP:

# 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

Licencia

MIT