mcp-server-sigma

📊 mcp-server-sigma

Supercharge your AI Agents with native Sigma Computing superpowers! ⚡
An enterprise-grade Model Context Protocol (MCP) server with 257 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 or --profile readonly (lists the 120 tools annotated readOnlyHint=true and refuses every other call).
• Destructive Safety Gates: All single-delete tools require explicit confirm=True; without it they change nothing and return a normal result (isError: false) asking the caller to re-call with confirm=true. Missing or invalid arguments return a tool error (isError: true) the model can correct, and so do other failed calls such as a member not found, an export that times out, or a rejected bulk-deactivate pattern (see docs/errors.md). A batch tool whose every item failed returns isError: true with "type": "batch_failed"; a partial success stays a normal result with "status": "partial_success", a <verb>_count, failed_count, results and errors, where each entry has id, status and result or error, alongside the field names each tool returned before; failed items that earlier releases listed in results are still there too (see docs/errors.md). Bulk destructive operations (admin_bulk_deactivate_members, admin_bulk_remove_team_members) are listed in full but refused at call time unless 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 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"

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

Twenty-two 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, 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, and admin_delete_translation_variant.

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 120 reads and false on the 137 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 257 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/

Note

Automated Drift Checks: The CI workflow (ci.yml) has a check-drift job, run weekly on Sunday afternoon Eastern time and on manual dispatch, that compares client methods against the live Sigma OpenAPI specification. If the drift scan runs on main and finds drift or exits with an error, the job automatically opens an issue in the repository. A failure in an earlier setup step fails the run without opening an issue.

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