Simba MCP Server

Simba는 베이지안 마케팅 믹스 모델링(MMM) 플랫폼입니다. 이 마케팅 믹스 모델링 MCP 서버는 AI 어시스턴트가 모델과 직접 상호작용할 수 있게 해줍니다 — 데이터 업로드, 모델 구축, 결과 확인, 예산 최적화 실행을 Claude, Cursor, 또는 Claude Code에서 자연어로 수행할 수 있습니다.

설치

pip install simba-mcp

또는 설치 없이 직접 실행하려면:

uvx simba-mcp

Related MCP server: Meta Ads MCP

빠른 시작

Cursor IDE

Cursor MCP 설정에 추가하세요 (작업 공간 또는 전역 설정의 .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

Claude Code MCP 구성에 추가하세요:

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

Anthropic MCP 커넥터와 함께 원격 Streamable HTTP 전송을 사용하세요:

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

사용 가능한 도구

예시 프롬프트

연결된 AI 어시스턴트와 함께 사용해 보세요:

모델 탐색:

"내 Simba 모델을 나열하고 가장 최근 완료된 모델의 채널 ROI 요약을 보여줘."

모델 구축:

"이 CSV 데이터를 Simba에 업로드하고 TV, Search, Social을 미디어 채널로 사용하여 새 MMM 모델을 만들어. KPI로 'revenue'를, 날짜 열로 'date'를 사용해."

진행 상황 확인:

"모델 a1b2c3d4의 피팅 상태는 어때?"

결과 가져오기:

"모델 a1b2c3d4의 진단 및 채널 기여도를 보여줘."

예산 최적화:

"모델 a1b2c3d4에 대해 총 예산 $1M, 12개월로 예산 최적화를 실행해. TV 범위를 5-40%, Search를 10-50%로 설정하고 균일한 laydown 가중치를 사용해."

반응 곡선:

"모델 a1b2c3d4의 반응 곡선을 보여줘. TV가 수익 체감에 도달하는 지출 수준은 어디야?"

시나리오 계획:

"모델 a1b2c3d4에 대해 다음 12주간의 시나리오 템플릿을 가져와. 그런 다음 TV를 20% 늘리고 Search를 10% 줄이는 시나리오를 실행해. 수익에 어떤 영향이 있을까?"

전체 워크플로:

"분석하고 싶은 마케팅 데이터가 있어. 먼저 스키마를 가져와서 필요한 형식을 확인한 다음, 데이터를 업로드하고 모델을 만들어. 완료되면 채널별 ROI를 보여줘."

에이전트 스킬

skills/ 디렉토리는 Agent Skills 형식(SKILL.md per skill)의 워크플로 스킬을 제공합니다 — 이 MCP 서버와 함께 스킬 인식 에이전트(예: Claude Code)에 설치하세요:

스킬은 문서화 산출물입니다 — 저장소에 포함되며, 와이어 프로토콜에는 포함되지 않습니다.

주의사항 및 팁

AI 에이전트와 인간 모두에게 흔히 발생하는 문제들:

호스팅 서버: 당신의 bearer token이 곧 로그인입니다

HTTP 배포에서는 각 요청이 호출자의 고유한 Authorization: Bearer simba_sk_... 토큰으로 인증됩니다 — 서버 측 공유 키는 없습니다. 도구 호출이 "No API key on this request"를 반환하면 MCP 클라이언트가 토큰을 보내지 않는 것입니다 (구성의 authorization_token / headers 설정을 확인하세요).

채널 이름은 정확히 일치해야 합니다

모델 결과는 채널의 활동 열 이름(예: "search_activity", "TV_impressions")으로 키가 지정되며, create_model에 전달한 channels[].name이 아닙니다. 키에는 공백이 포함될 수 있으며 일치는 대소문자 및 공백 구분입니다 — 최적화 및 시나리오 도구는 이를 사전 키로 사용합니다.

항상 먼저 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 이후 피팅은 모든 *_median 옆에 *_mean을 추가합니다 — 중앙값이 표시되고, 평균이 한계 수익 곡선과 일치합니다), mroi_periods (옵트인 전용 — 기간별 한계 ROI 시리즈; 기본 페이로드에는 절대 포함되지 않으며 이름으로 요청해야 합니다), model_stats, actual_vs_model, long_run_rollup, optimizer, predictions, posterior, financials, model_config. 서버가 이 문서보다 최신인 경우 응답의 sections_available 필드가 권위 있는 정보입니다.

모델은 model_hash로 식별됩니다

모든 모델 엔드포인트는 create_model 및 list_models에서 반환된 문자열 model_hash(예: "f835671a25")를 사용합니다.

API 키 관리는 의도적으로 노출되지 않습니다

/api/v1/keys 엔드포인트(API 키 생성/목록/폐기)는 세션 인증 전용이며 의도적으로 MCP 도구가 없습니다: 하나의 키를 보유한 서버는 키를 생성하거나 폐기할 수 없어야 합니다. 키는 Simba UI(프로필 → API 키)에서 관리하세요.

최적화 배열, 스칼라 아님

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에 나타나야 합니다. Bounds 값은 total_budget의 백분율(0-100)이며 통화 금액이 아닙니다.

시나리오 템플릿에서 NaN 정리

get_scenario_template의 템플릿에는 과거 데이터가 없는 채널에 대해 NaN/null이 포함될 수 있습니다. run_scenario에 전달하기 전에 0으로 바꾸세요:

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 MB (API 강제).

• 최소 행 수: get_data_schema → x-simba-constraints.min_rows 확인; 업로드 응답의 warnings 필드가 권위 있는 정보입니다. 행이 많을수록 사후 분포가 더 정밀해집니다 (104주 이상의 주간 행 권장).

• 미디어 열: 채널별 {channel}_activity 및 {channel}_spend.

• 비활성 기간에는 공백이나 NA 대신 0을 사용하세요.

• 큰 파일? csv_content 대신 csv_path(로컬 파일 경로)를 전달하세요 — 서버가 대화를 통해 CSV를 전달하는 대신 직접 읽습니다. 로컬(stdio) 서버 전용; HTTP/SSE 배포에서는 SIMBA_MCP_ALLOW_LOCAL_FILES=1이 아닌 한 비활성화됩니다.

일반적인 오류

직접 API 액세스

MCP 서버는 Simba REST API를 래핑합니다. 스크립팅, CI/CD 또는 MCP가 없는 환경에서는 API를 직접 호출할 수 있습니다.

MCP vs 직접 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 서버는 Simba REST API에서 사용하는 것과 동일한 API 키로 인증합니다. 필요한 범위로 키를 생성하세요:

1. Simba UI에서 프로필 > API 키로 이동

2. 키 생성 클릭

3. 범위 설정: ingest, read:models, read:results, create:models, optimize, scenario

4. 키 복사 (한 번만 표시됨)

키 제공 방식은 서버가 실행되는 위치에 따라 다릅니다:

• 로컬 (stdio — Cursor, Claude Code): MCP 구성에서 SIMBA_API_KEY 환경 변수로 설정 (위의 예시 참조).

• 호스팅 (https://demo.simba-mmm.com/mcp): HTTP Authorization: Bearer 헤더로 전송 — Claude MCP 커넥터 구성의 authorization_token 필드. 모든 호출자는 자신의 키를 사용합니다 (v0.2.2+): 서버는 호출자 간에 ID를 공유하지 않으며, 키가 없는 요청은 안내가 포함된 구조화된 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