mcp-server-sigma

📊 mcp-server-sigma

AI エージェントに Sigma Computing のネイティブ機能を活用しましょう！ ⚡
コネクション、ワークブック、データモデル、メンバー、チーム、デプロイ、Webhook、マルチテナント運用、そしてお好みの AI アシスタントですぐに使える複合ワークフローレシピを網羅する 257 個のツールを備えた、エンタープライズグレードの Model Context Protocol（MCP）サーバーです。

⚠️ 免責事項と安全上の警告

重要

コミュニティプロジェクトに関する免責事項
mcp-server-sigma は、独立したオープンソースのコミュニティプロジェクトです。Sigma Computing, Inc. との提携、同社による後援、承認、サポートは一切ありません。「Sigma Computing」 は Sigma Computing, Inc. の商標です。

警告

認証情報と安全に関するお知らせ
このサーバーは、Sigma 組織にスコープが設定された API 認証情報を使用します。ツールによっては、ワークブック、ユーザー、チーム、データモデルを変更できます。

• 読み取り専用モード： 変更リスクなしで安全に実行するには、SIGMA_MCP_READONLY=1 または --profile readonly を設定してください（readOnlyHint=true が注釈された 120 個のツールを一覧表示し、それ以外のすべての呼び出しを拒否します）。
• 破壊的操作に対する安全ゲート： 単一項目の削除ツールでは、すべて明示的に confirm=True を指定する必要があります。指定しない場合は何も変更せず、呼び出し側に confirm=true を付けて再呼び出しするよう求める通常の結果（isError: false）を返します。引数が不足している場合や無効な場合は、モデルが修正できるツールエラー（isError: true）を返します。メンバーが見つからない、エクスポートがタイムアウトする、一括無効化のパターンが拒否されるなど、その他の呼び出し失敗も同様です（docs/errors.md を参照）。バッチツールですべての項目が失敗した場合は、"type": "batch_failed" を含む isError: true を返します。一部が成功した場合は、"status": "partial_success"、<verb>_count、failed_count、results、errors を含む通常の結果を返します。各エントリーには id、status、result または error が含まれ、各ツールが以前に返したフィールド名も併せて含まれます。以前のリリースで results に記載されていた失敗項目も引き続き含まれます（docs/errors.md を参照）。一括破壊的操作（admin_bulk_deactivate_members、admin_bulk_remove_team_members）は full に一覧表示されますが、SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1 が設定されていない限り、呼び出し時に拒否されます。
• 本番環境にデプロイする前に、SECURITY.md をお読みください。

💡 これが存在する理由

Sigma Computingには、どのように自動化するかを左右する独自のアーキテクチャ上の非対称性があります。

1. データモデルは100％コードで表現できます： データモデルの構築、列や結合、SQLロジックの定義、JSON仕様の更新、API経由でのウェアハウスソースの切り替えをプログラムで実行できます。
2. ワークブックのレイアウトは主にUIで操作します： Sigmaではワークブック仕様用のベータ版エンドポイント（/v2/workbooks/spec）が導入されていますが、レイアウト要素をゼロからプログラムで構築するのは依然として非常に複雑です。

BIダッシュボードを自動化するための標準的な方法は次のとおりです：
SigmaのUIでレイアウトを一度構築してテンプレートとして保存し、その後はプログラムでテンプレートをインスタンス化し、ソースを切り替えます！ 🎨 ➡️ 🤖

複合レシピツール（workbooks_deploy_template_to_folderやelements_swap_workbook_sourcesなど）は、この一連のパターンを1回のMCPツール呼び出しで自動化します（中間ステップが失敗した場合は、ステップの進捗状況または部分的な失敗の詳細を構造化して返します）：

graph TD
    UI["Sigma UI"] -->|"1. Build Layout Once & Save"| TPL["Sigma Template"]
    Agent["AI Agent / LLM"] -->|"2. Call workbooks_deploy_template_to_folder"| MCP["mcp-server-sigma"]
    MCP -->|"POST /v2/templates/{id}/instantiate"| API1["Instantiate Workbook"]
    MCP -->|"POST /v2/workbooks/{id}/swap_sources"| API2["Swap Warehouse Sources"]
    API2 -->|"Delivered"| Dest["Target Customer Folder"]

📦 クイックスタートとインストール

1. pipまたはuvでインストールする

pip install mcp-server-sigma
# or with uv
uv pip install mcp-server-sigma

またはDockerで実行する

docker run --rm -i --env-file .env \
  ghcr.io/christianclaudio/mcp-server-sigma:latest

イメージのデフォルトコマンドはstdioです。コンテナからStreamable HTTPを提供するには、コンテナ内で0.0.0.0にバインドし、トークンを渡します。トークンをコマンドラインに記述しないでください（シェルの履歴やpsに表示されます）。.envにSIGMA_MCP_AUTH_TOKENを設定するか、環境変数としてエクスポートし、-eには名前だけを渡してください：

export SIGMA_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"  # or read it from your secret store
docker run --rm -p 8000:8000 --env-file .env \
  -e SIGMA_MCP_AUTH_TOKEN \
  ghcr.io/christianclaudio/mcp-server-sigma:latest \
  --transport streamable-http --host 0.0.0.0 --port 8000 --allowed-host mcp.example.com

2. 環境変数を設定する

export SIGMA_CLIENT_ID="your-client-id"
export SIGMA_CLIENT_SECRET="your-client-secret"
export SIGMA_API_BASE_URL="https://api.us-a.aws.sigmacomputing.com"

ヒント

組織のリージョンに割り当てられたAPIベースURLを使用してください。

🔌 AI アシスタントと IDE 向けの統合ガイド

mcp-server-sigma は、標準の stdio または streamable-http を介して、主要な AI アシスタント、IDE、CLI ツールすべてとシームレスに連携します。

{
  "mcpServers": {
    "sigma": {
      "command": "sigma-mcp",
      "env": {
        "SIGMA_CLIENT_ID": "your-client-id",
        "SIGMA_CLIENT_SECRET": "your-client-secret",
        "SIGMA_API_BASE_URL": "https://api.us-a.aws.sigmacomputing.com"
      }
    }
  }
}

claude mcp add sigma -- sigma-mcp

{
  "mcpServers": {
    "sigma": {
      "command": "sigma-mcp",
      "args": [],
      "env": {
        "SIGMA_CLIENT_ID": "your-client-id",
        "SIGMA_CLIENT_SECRET": "your-client-secret",
        "SIGMA_API_BASE_URL": "https://api.us-a.aws.sigmacomputing.com"
      }
    }
  }
}

# Source environment variables from a protected file or secret manager
source .env

# Launch server on HTTP localhost port 8000 for local clients
sigma-mcp --transport streamable-http --host 127.0.0.1 --port 8000

{
  "mcpServers": {
    "sigma": {
      "command": "sigma-mcp",
      "env": {
        "SIGMA_CLIENT_ID": "your-client-id",
        "SIGMA_CLIENT_SECRET": "your-client-secret",
        "SIGMA_API_BASE_URL": "https://api.us-a.aws.sigmacomputing.com"
      }
    }
  }
}

mcpServers:
  - name: sigma
    command: sigma-mcp
    env:
      SIGMA_CLIENT_ID: "your-client-id"
      SIGMA_CLIENT_SECRET: "your-client-secret"
      SIGMA_API_BASE_URL: "https://api.us-a.aws.sigmacomputing.com"

{
  "mcpServers": {
    "sigma": {
      "command": "sigma-mcp",
      "env": {
        "SIGMA_CLIENT_ID": "your-client-id",
        "SIGMA_CLIENT_SECRET": "your-client-secret",
        "SIGMA_API_BASE_URL": "https://api.us-a.aws.sigmacomputing.com"
      }
    }
  }
}

{
  "mcpServers": {
    "sigma": {
      "type": "local",
      "command": "sigma-mcp",
      "env": {
        "SIGMA_CLIENT_ID": "${COPILOT_MCP_SIGMA_CLIENT_ID}",
        "SIGMA_CLIENT_SECRET": "${COPILOT_MCP_SIGMA_CLIENT_SECRET}",
        "SIGMA_API_BASE_URL": "https://api.us-a.aws.sigmacomputing.com",
        "SIGMA_MCP_READONLY": "1"
      },
      "tools": ["workbooks_get_workbook", "workbooks_list_workbooks", "datasets_get_data_model"]
    }
  }
}

cortex mcp add sigma-tools -- sigma-mcp

🛡️ 安全管理

環境変数を使用して動作を設定します。

🧭 プロファイル

--profile または SIGMA_MCP_PROFILE でプロファイルを選択します（デフォルトは full）。すべてのプロファイルで、5つのドメイン（workbooks、datasets、elements、workspace、admin）がマウントされます。ジョブプロファイルでは、特定のジョブ向けに明示的に列挙されたツール名のみが公開されます。プロンプトとリソースは、すべてのプロファイルで引き続き利用できます。サーバーのビルド時に、列挙された各名前が全カタログと照合されるため、プロファイルが不明な場合やリストに誤記がある場合は、起動時に ValueError が発生します。

22個のツールはどのジョブプロファイルにも含まれておらず、full でのみ利用できます：workspace_delete_file、workspace_update_file、workspace_create_tag、workspace_delete_tag、admin_list_translations、admin_bulk_deactivate_members、admin_bulk_remove_team_members、admin_api_capabilities、admin_list_recent_webhooks、workspace_update_tag、admin_list_api_credentials、admin_get_api_credential、admin_create_api_credential、admin_update_api_credential、admin_delete_api_credential、admin_get_translation、admin_get_translation_variant、admin_create_translation、admin_update_translation、admin_update_translation_variant、admin_delete_translation、admin_delete_translation_variant。

読み取り専用の動作

• MCP の readOnlyHint 注釈だけで、ツールが読み取り専用かどうかが決まります。すべてのツールに明示的な宣言があります。読み取り120件は true、書き込み137件は false です。注釈がないツールや readOnlyHint がないツールは、書き込みとして扱われます。
• --profile readonly または SIGMA_MCP_READONLY=1（任意のプロファイルで指定）を設定すると、読み取り専用ツールのみが一覧表示されます。また、ReadOnlyGateMiddleware は、フィルターで非表示にされた書き込みを含め、読み取り専用ではない実際のツールへの呼び出しを拒否します。拒否された場合は、isError: true を含むツール結果が返されます。
• サーバー上に存在しない名前を指定した場合は、直接呼び出す場合も call_tool 経由の場合も、FastMCP の通常の Unknown tool エラーが返されるため、誤記がブロックされたツールとして報告されることはありません。
• Tool Search が有効な場合、ゲートは call_tool がラップするツールを確認します。call_tool 経由の読み取りは成功し、書き込みは拒否されます。Tool Search が無効な場合、call_tool はサーバー上のツールではないため、呼び出すと Unknown tool: 'call_tool' が返されます。
• ゲートがサービングサーバーを確認できない場合、呼び出しは拒否されます。

一括処理ゲート

admin_bulk_deactivate_members と admin_bulk_remove_team_members は full に列挙されています。SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1 が設定されていない限り、admin ドメインガードは呼び出し時にこれらを拒否します（isError: true）。また、ハンドラーには独自の confirm／dry_run セーフガードがあります。読み取り専用モードでは、これらは非表示になり、呼び出しも拒否されます。

ツール検索とコードモード

tools/list はデフォルトではフラットです。検出はオプトイン方式で、full の場合にのみ追加されます。

• --enable-tool-search / SIGMA_MCP_ENABLE_TOOL_SEARCH=1 を指定すると、tools/list が search_tools と call_tool に置き換わります。バックエンドは regex（デフォルト）または bm25（--tool-search-backend / SIGMA_MCP_TOOL_SEARCH_BACKEND）です。
• --enable-code-mode / SIGMA_MCP_ENABLE_CODE_MODE=1 を指定すると、FastMCP の実験的なコードモード（search、get_schema、execute）が追加されます。コードモードには、パッケージの code-mode エクストラ（pydantic-monty を同梱する fastmcp[code-mode]）に含まれるサンドボックスが必要です。pip install "mcp-server-sigma[code-mode]" または uvx "mcp-server-sigma[code-mode]" --enable-code-mode を実行してください。サンドボックスがない場合、警告が表示されてコードモードはスキップされ、フラットなカタログが提供されます。
• 両方を有効にすると ValueError が発生します。別のプロファイルでいずれかを指定すると、警告が記録され、フラットなリストが維持されます。
• search_tools、search、get_schema はカタログの読み取りのみを行い、readOnlyHint=true と注釈されています。読み取り専用モードでは、コードモードの execute は拒否されます。

📊 機能とツールの概要

full プロファイルには257 個のツールが一覧表示されます。すべてのツール名は、ツールが属するドメイン名から始まります。

scripts/check_tool_contract.py は、ライブレジストリとの件数のずれがあると CI を失敗させます。破壊的な一括操作ツール 2 個（admin_bulk_deactivate_members、admin_bulk_remove_team_members）は admin の件数に含まれており、SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1 が設定されていない場合、呼び出し時に拒否されます。

🍳 複合ワークフローのレシピ

これらの高レベルツールは、複数ステップの API シーケンスを単一のアトミックな呼び出しにまとめます。

📐 MCP 2.0 のヒントと安全性アノテーション

すべてのツールには、AI クライアントがユーザー権限の確認を行う際に役立つ、構造化された MCP ヒントが含まれています。

🧮 Sigma の数式を書く

AI モデルは Sigma の数式を書く際に、SQL や Excel の関数を頻繁に幻覚します（例：List() の代わりに ArrayAgg() を使用するなど）。
Sigma の数式を書く前に、組み込みのリファレンスツールを呼び出してください。

# Model prompt helper
Use tool `elements_formula_pitfalls` to check formula syntax rules.

構文の詳細については、docs/formulas.md をご覧ください。

👩‍💻 ローカルでの開発とテスト

# Install dev tools
pip install -e ".[dev]"

# Run full test suite with 100% statement line coverage enforcement
pytest --cov=src/sigma_mcp --cov-fail-under=100 --cov-report=term-missing

# Run OpenAPI drift check
python scripts/check_openapi_drift.py

# Run MCP tool contract validation
python scripts/check_tool_contract.py

# Code formatting & type checking
ruff check src/
ruff format --check .
mypy --strict src/

メモ

自動ドリフトチェック：CI ワークフロー（ci.yml）には check-drift ジョブがあります。このジョブは毎週日曜日の東部時間の午後と手動実行時に動作し、クライアントメソッドを Sigma の最新の OpenAPI 仕様と照合します。ドリフトスキャンが main で実行され、ドリフトが見つかった場合、またはエラーで終了した場合、ジョブはリポジトリに Issue を自動的に作成します。先行するセットアップ手順が失敗した場合は、Issue を作成せずに実行が失敗します。

🤝 貢献とコミュニティ

貢献を歓迎します。開発ルールについては CONTRIBUTING.md、セキュリティに関する報告については SECURITY.md、コミュニティの行動規範については CODE_OF_CONDUCT.md をお読みください。

📜 ライセンス

MIT License。
Copyright (c) 2026 Christian Claudio.

免責事項：Sigma Computing, Inc. との提携、支援、または承認を受けたものではありません。