Simba MCP Server

Simba — это платформа для байесовского маркетинг-микс моделирования (MMM). Этот MCP-сервер для маркетинг-микс моделирования позволяет ИИ-ассистентам взаимодействовать с вашими моделями напрямую — загружать данные, строить модели, проверять результаты и запускать оптимизацию бюджета с помощью естественного языка в Claude, Cursor или Claude Code.

Установка

pip install simba-mcp

Или запустите напрямую без установки:

uvx simba-mcp

Related MCP server: Meta Ads MCP

Быстрый старт

Cursor IDE

Добавьте в настройки MCP для Cursor (.cursor/mcp.json в рабочей области или глобальные настройки):

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

Claude Code

Добавьте в конфигурацию MCP для Claude Code:

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

Используйте удалённый транспорт Streamable HTTP с коннектором MCP от 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"],
)

Доступные инструменты

Примеры запросов

Попробуйте эти примеры с любым подключённым ИИ-ассистентом:

Изучение моделей:

«Перечисли мои модели Simba и покажи сводку ROI по каналам для самой последней завершённой модели.»

Построение модели:

«Загрузи эти CSV-данные в Simba и создай новую MMM-модель с TV, Search и Social в качестве медиаканалов. Используй "revenue" как KPI и "date" как столбец даты.»

Проверка прогресса:

«Каков статус подгонки модели a1b2c3d4?»

Получение результатов:

«Покажи диагностику модели и вклад каналов для модели a1b2c3d4.»

Оптимизация бюджета:

«Запусти оптимизацию бюджета для модели a1b2c3d4 с общим бюджетом $1M на 12 месяцев. Установи границы TV 5–40%, а Search 10–50%. Используй равномерные веса развёртывания.»

Кривые отклика:

«Покажи кривые отклика для модели a1b2c3d4. При каком уровне расходов TV достигает убывающей отдачи?»

Планирование сценариев:

«Получи шаблон сценария для модели a1b2c3d4 на следующие 12 недель. Затем запусти сценарий, в котором я увеличиваю TV на 20% и сокращаю Search на 10%. Что произойдёт с выручкой?»

Полный рабочий процесс:

«У меня есть маркетинговые данные, которые я хочу проанализировать. Сначала получи схему, чтобы я знал, какой формат нужен, затем загрузи мои данные, создай модель, и когда она будет готова, покажи ROI по каналам.»

Навыки агента

В каталоге skills/ поставляются рабочие навыки в формате Agent Skills (SKILL.md для каждого навыка) — установите их в любого агента, поддерживающего навыки (например, Claude Code), вместе с этим MCP-сервером:

Навыки — это документационные артефакты: они живут в репозитории, а не в сетевом протоколе.

Подводные камни и советы

То, что часто вызывает затруднения и у ИИ-агентов, и у людей:

Хостируемый сервер: ваш bearer-токен и есть ваш логин

На HTTP-развёртываниях каждый запрос аутентифицируется собственным токеном вызывающей стороны Authorization: Bearer simba_sk_... — общего серверного ключа нет. Если вызовы инструментов возвращают "No API key on this request", ваш MCP-клиент не отправляет токен (проверьте настройку authorization_token / заголовков в его конфигурации).

Имена каналов должны точно совпадать

Результаты модели привязаны к имени столбца активности канала (например, "search_activity", "TV_impressions"), а не к channels[].name, который вы передали в create_model. Ключи могут содержать пробелы, и сопоставление чувствительно к регистру и пробелам — инструменты оптимизатора и сценариев используют их как ключи словаря.

Всегда сначала вызывайте get_model_results с sections="channel_summary", чтобы увидеть точные ключи каналов, а затем используйте их дословно в полезных нагрузках оптимизатора/сценария.

Разделы результатов

get_model_results предоставляет следующие разделы (запрашивайте только то, что нужно, через sections=): channel_summary, contributions (пространство KPI/единиц — множитель не применяется), coefficients (таблица выручки по периодам и каналам), params, decay_curves, response_curves, marginal_curves, saturation, mroi_summary (предельная ROI при текущих расходах с 94% HDI; после подгонок #591 добавляются скаляры соглашений allperiods_unweighted / spendweighted_active, а после подгонок #629 — *_mean рядом с каждым *_median — отображается медиана, а среднее согласуется с кривой предельной выручки), mroi_periods (только по запросу — ряд предельной ROI по периодам; никогда не входит в стандартную полезную нагрузку, запрашивайте по имени), model_stats, actual_vs_model, long_run_rollup, optimizer, predictions, posterior, financials, model_config. Поле sections_available в ответе является авторитетным, если сервер новее этой документации.

Модели идентифицируются по model_hash

Все конечные точки моделей используют строку model_hash (например, "f835671a25"), возвращаемую create_model и list_models.

Управление API-ключами намеренно не раскрыто

Конечные точки /api/v1/keys (создание/список/отзыв API-ключей) доступны только через сеансовую аутентификацию и по замыслу не имеют инструментов MCP: сервер, владеющий одним ключом, не должен иметь возможности создавать или отзывать ключи. Управляйте ключами в интерфейсе Simba (Profile → API Keys).

Массивы оптимизатора, а не скаляры

laydown_weights и period_cpm должны быть объектами массивов, каждый массив должен содержать ровно num_periods элементов:

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

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

Одни и те же ключи каналов должны присутствовать в bounds, laydown_weights и period_cpm. Значения границ — это проценты (0–100) от total_budget, а не денежные суммы.

Очистка NaN из шаблонов сценариев

Шаблон из get_scenario_template может содержать NaN/null для каналов без исторических данных. Замените их на 0 перед передачей в 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

Три конечные точки асинхронны

Они возвращают 202 и требуют опроса:

Опрашивайте каждые 5–10 секунд. Проверяйте поле status на значение "complete" или "failed".

Требования к загрузке данных

• Только CSV (не Excel). Максимум 10 МБ (ограничение API).

• Минимум строк: проверьте get_data_schema → x-simba-constraints.min_rows; поле warnings в ответе загрузки является авторитетным. Больше строк = более точные апостериорные распределения (рекомендуется 104+ недельных строк).

• Столбцы медиа: {channel}_activity и {channel}_spend для каждого канала.

• Используйте 0 для неактивных периодов, а не пустые значения или NA.

• Большой файл? Передайте csv_path (локальный путь к файлу) вместо csv_content — сервер прочитает его напрямую, а не через разговор. Только для локальных (stdio) серверов; отключено на HTTP/SSE-развёртываниях, если не задано SIMBA_MCP_ALLOW_LOCAL_FILES=1.

Частые ошибки

Прямой доступ к API

MCP-сервер оборачивает REST API Simba. Для скриптов, CI/CD или сред без MCP вы можете вызывать API напрямую.

Когда использовать MCP, а когда прямой API

Оба варианта используют одни и те же API-ключи с одинаковыми областями действия.

Быстрый старт (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}")

Быстрый старт (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-ключа

MCP-сервер аутентифицируется с помощью тех же API-ключей, что и REST API Simba. Создайте ключ с необходимыми областями действия:

1. Перейдите в Профиль > API-ключи в интерфейсе Simba

2. Нажмите Создать ключ

3. Установите области действия: ingest, read:models, read:results, create:models, optimize, scenario

4. Скопируйте ключ (показывается только один раз)

Способ передачи ключа зависит от того, где запущен сервер:

• Локально (stdio — Cursor, Claude Code): задайте его как переменную окружения SIMBA_API_KEY в вашей конфигурации MCP (примеры выше).

• Хостинг (https://demo.simba-mmm.com/mcp): отправляйте его в HTTP-заголовке Authorization: Bearer — поле authorization_token в конфигурации коннектора MCP для Claude. Каждый вызывающий использует свой собственный ключ (v0.2.2+): сервер никогда не разделяет идентичность между вызывающими, запрос без ключа получает структурированную ошибку 401 с рекомендациями, и вы видите только модели своего собственного аккаунта.

Конфигурация

Режимы транспорта

Сервер поддерживает все режимы транспорта 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

Лицензия

MIT