🚀 mcp-server-sigma

Supercharge your AI Agents with native Sigma Computing superpowers! ⚡
An enterprise-grade Model Context Protocol (MCP) server with 155 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

[!IMPORTANT] Community Project Disclaimer
mcp-server-sigma is an independent open-source community project. It is not affiliated with, sponsored by, endorsed by, or supported by Sigma Computing, Inc. "Sigma Computing" is a trademark of Sigma Computing, Inc.

[!WARNING] Credentials & Safety Notice
This server uses API credentials scoped to your Sigma organization. Tools can mutate workbooks, users, teams, and data models.

• Read-Only Mode: To run safely without mutation risk, set SIGMA_MCP_READONLY=1 (grants 83 read-only tools).
• Destructive Safety Gates: All single-delete tools require explicit confirm=True. Bulk destructive operations (sigma_bulk_deactivate_members, sigma_bulk_remove_team_members) are disabled by default and require SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1.
• Read SECURITY.md before deploying to production.

💡 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 sigma_deploy_template_to_folder and sigma_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 sigma_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

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"

[!TIP] Use the API base URL assigned to your organization's region.

🔌 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": {
      "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": ["sigma_get_workbook", "sigma_list_workbooks", "sigma_get_data_model"]
    }
  }
}

cortex mcp add sigma-tools -- sigma-mcp

🛡️ Safety & Security Controls

Configure behavior using environment variables:

📊 Feature & Tool Summary

The server registers 155 tools by default across the following domain modules:

Note: Domain categories overlap slightly. The 2 bulk-destructive tools (sigma_bulk_deactivate_members, sigma_bulk_remove_team_members) are excluded by default and bring the total to 157 when enabled.

🍳 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 `sigma_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/

[!NOTE] Automated Drift Checks: This repository runs a weekly scheduled GitHub Action (sigma-drift-monitor.yml) that compares client methods against the live Sigma OpenAPI specification. If drift is detected, the workflow automatically opens an issue in the repository.

🤝 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.