📊 mcp-server-sigma

Supercharge your AI Agents with native Sigma Computing superpowers! ⚡
An enterprise-grade Model Context Protocol (MCP) server with 172 tools covering connections, workbooks, data models, members, teams, deployments, webhooks, multi-tenant operations, and composite workflow recipes straight to your favorite AI assistant.

⚠️ Disclaimers & Safety Warnings

💡 Why This Exists

Sigma Computing has a unique architectural asymmetry that shapes how you automate it:

1. Data Models are 100% Code-Representable: You can programmatically construct data models, define columns, joins, and SQL logic, update JSON specs, and swap warehouse sources via API.
2. Workbook Layouts are primarily UI-driven: While Sigma has introduced Beta endpoints for workbook specifications (/v2/workbooks/spec), programmatically constructing layout elements from scratch remains highly complex.

The canonical path to automated BI dashboards is:
Build the layout once in the Sigma UI, save it as a template, then instantiate and source-swap it programmatically forever after! 🎨 ➡️ 🤖

Our composite recipe tools (like workbooks_deploy_template_to_folder and elements_swap_workbook_sources) automate this exact pattern in a single MCP tool call (returning structured step progress or partial failure details if an intermediate step fails):

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

📦 Quickstart & Installation

1. Install via pip or uv

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

Or run via Docker

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

The image's default command is stdio. To serve Streamable HTTP from the container, bind 0.0.0.0 inside it and pass a token. Keep the token off the command line (it shows up in shell history and ps): put SIGMA_MCP_AUTH_TOKEN in .env, or export it and pass the name alone with -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. Set Environment Variables

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"

🔌 Integration Guides for AI Assistants & IDEs

mcp-server-sigma works seamlessly with all major AI assistants, IDEs, and CLI tools via standard stdio or streamable-http.

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

🛡️ Safety & Security Controls

Configure behavior using environment variables:

🧭 Profiles

Pick a profile with --profile or SIGMA_MCP_PROFILE (default full). Every profile mounts all five domains (workbooks, datasets, elements, workspace, admin). Job profiles then expose only an explicit list of tool names for one job; prompts and resources stay available on every profile. Each listed name is checked against the full catalog when the server builds, so an unknown profile or a typo in a list fails at startup with ValueError.

Nine tools are in no job profile and are reachable only in 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, and admin_list_recent_webhooks.

Read-only behavior

• The MCP readOnlyHint annotation is the only thing that decides whether a tool is read-only. Every tool declares it explicitly: true on the 90 reads and false on the 82 writes. A tool with no annotation or no readOnlyHint counts as a write.
• --profile readonly or SIGMA_MCP_READONLY=1 (on any profile) lists only the read-only tools, and ReadOnlyGateMiddleware refuses any call to a real tool that is not read-only, including a write the filter hid. A refusal comes back as a tool result with isError: true.
• A name that is not a tool on the server gets FastMCP's normal Unknown tool error, directly or through call_tool, so a typo is never reported as a blocked tool.
• With Tool Search on, the gate checks the tool that call_tool wraps. Reads through call_tool work and writes are refused. Without Tool Search, call_tool is not a tool on the server, so a call to it gets Unknown tool: 'call_tool'.
• If the gate cannot see the serving server, it refuses the call.

Bulk gate

admin_bulk_deactivate_members and admin_bulk_remove_team_members are listed in full. The admin domain guard refuses them at call time (isError: true) unless SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1, and the handlers keep their own confirm / dry_run safeguards. Read-only mode hides and refuses them.

Tool Search and Code Mode

tools/list is flat by default. Discovery is opt-in and attaches only on full:

• --enable-tool-search / SIGMA_MCP_ENABLE_TOOL_SEARCH=1 replaces tools/list with search_tools and call_tool. The backend is regex (default) or bm25 (--tool-search-backend / SIGMA_MCP_TOOL_SEARCH_BACKEND).
• --enable-code-mode / SIGMA_MCP_ENABLE_CODE_MODE=1 attaches FastMCP's experimental Code Mode (search, get_schema, execute). Code Mode needs the sandbox from the package's code-mode extra (fastmcp[code-mode], which ships pydantic-monty): pip install "mcp-server-sigma[code-mode]" or uvx "mcp-server-sigma[code-mode]" --enable-code-mode. Without it, Code Mode is skipped with a warning and the flat catalog is served.
• Turning on both raises ValueError. Asking for either on another profile logs a warning and keeps the flat list.
• search_tools, search and get_schema only read the catalog and are annotated readOnlyHint=true. Under read-only, Code Mode execute is refused.

📊 Feature & Tool Summary

The full profile lists 172 tools. Every tool name starts with the domain it is mounted under:

scripts/check_tool_contract.py fails CI if these counts drift from the live registry. The 2 bulk-destructive tools (admin_bulk_deactivate_members, admin_bulk_remove_team_members) are in the admin count and are refused at call time unless SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1.

🍳 Composite Workflow Recipes

These high-level tools bundle multi-step API sequences into a single atomic call:

📐 MCP 2.0 Hints & Safety Annotations

Every tool includes structured MCP hints to assist AI clients with user permission prompts:

🧮 Writing Sigma Formulas

AI models frequently hallucinate SQL or Excel functions when writing Sigma formulas (e.g. using ArrayAgg() instead of List()).
Before writing any Sigma formula, call the built-in reference tool:

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

See docs/formulas.md for full syntax details.

👩‍💻 Local Development & Testing

# 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/

🤝 Contributing & Community

Contributions are welcome! Please read CONTRIBUTING.md for development rules, SECURITY.md for security reporting, and CODE_OF_CONDUCT.md for community standards.

📜 License

MIT License.
Copyright (c) 2026 Christian Claudio.

Disclaimer: Not affiliated with, sponsored by, or endorsed by Sigma Computing, Inc.