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 コネクタ）

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 で、総予算 100 万ドル、12 か月間の予算最適化を実行して。TV の範囲は 5〜40%、Search は 10〜50% に設定して。均一なレイダウンウェイトを使って。」

反応曲線:

「モデル a1b2c3d4 の反応曲線を見せて。TV はどの支出レベルで収穫逓減になる？」

シナリオ計画:

「モデル a1b2c3d4 の今後 12 週間のシナリオテンプレートを取得して。次に、TV を 20% 増やし、Search を 10% 減らすシナリオを実行して。収益はどうなる？」

完全なワークフロー:

「分析したいマーケティングデータがあります。まずスキーマを取得して必要な形式を確認し、次にデータをアップロードしてモデルを作成し、完了したらチャネル別 ROI を見せて。」

エージェントスキル

skills/ ディレクトリには、Agent Skills 形式（スキルごとに SKILL.md）のワークフロースキルが同梱されています。この MCP サーバーと一緒に、スキル対応エージェント（例: Claude Code）にインストールしてください:

スキルはドキュメント成果物であり、リポジトリに同梱されます。ワイヤープロトコルには含まれません。

落とし穴とヒント

AI エージェントと人間の両方がよくつまずく点:

ホスト型サーバー: ベアラートークンがそのままログイン

HTTP デプロイメントでは、各リクエストは呼び出し元自身の Authorization: Bearer simba_sk_... トークンで認証されます。サーバー側の共有キーはありません。ツール呼び出しが "No API key on this request" を返す場合、MCP クライアントがトークンを送信していません（設定の authorization_token / ヘッダー設定を確認してください）。

チャネル名は完全一致

モデル結果は、create_model に渡した channels[].name ではなく、チャネルのアクティビティ列名（例: "search_activity"、"TV_impressions"）でキー付けされます。キーにはスペースを含めることができ、一致は大文字小文字とスペースに敏感です。オプティマイザーとシナリオツールはこれらを辞書キーとして使用します。

必ず最初に 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 ツールは設計上ありません。1 つのキーを保持するサーバーがキーを発行または失効できてはならないからです。キーの管理は 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 に含まれている必要があります。境界値は 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

3 つのエンドポイントは非同期

これらは 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（ローカルファイルパス）を渡してください。サーバーが会話を介さず直接読み取ります。ローカル（stdio）サーバーのみ。HTTP/SSE デプロイメントでは SIMBA_MCP_ALLOW_LOCAL_FILES=1 が設定されていない限り無効です。

よくあるエラー

直接APIアクセス

MCPサーバーはSimba REST APIをラップしています。スクリプト、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サーバーは、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