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.

🧡 Claude Desktop & Claude Code

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

For Claude Code CLI:

claude mcp add sigma -- sigma-mcp

♊ Google Antigravity & Gemini CLI

Add to your project's .agents/mcp_config.json (or global ~/.gemini/config/mcp_config.json):

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

🤖 OpenAI Codex & Local HTTP Clients

Run in network transport mode (Streamable HTTP) for local CLI & agent extensions:

# 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

Point your local Codex / Streamable HTTP client to http://127.0.0.1:8000/mcp. When SIGMA_MCP_AUTH_TOKEN is set, the client must send Authorization: Bearer <token>; requests without it, or with a different token, get HTTP 401.

HTTP transports follow the MCP guidance that a local server binds to localhost, and require a bearer token whenever the server is reachable beyond it:

• On 127.0.0.1, ::1 or localhost (the --host default is 127.0.0.1), HTTP runs with or without SIGMA_MCP_AUTH_TOKEN; without it, a warning says requests are not authenticated.
• On any other host (0.0.0.0, ::, a LAN address), the server refuses to start (exit code 2) unless SIGMA_MCP_AUTH_TOKEN is set, or SIGMA_MCP_ALLOW_UNAUTHENTICATED_BIND=1 accepts an unauthenticated bind (logged as a warning), for example behind a gateway that authenticates for you.
• The token is attached when the server is built, so fastmcp run src/sigma_mcp/server.py:mcp --transport http and an ASGI host mounting mcp.http_app() enforce it too. Those entry points do not know the bind host, so they cannot refuse a public bind; use sigma-mcp for that policy.
• In the default (stateful) HTTP mode, a session idle for 30 minutes expires: its next request gets HTTP 404 and the client must start a new session. Change this with FastMCP's session_idle_timeout (on http_app()) or FASTMCP_HTTP_SESSION_IDLE_TIMEOUT (seconds, or none to never expire); see the FastMCP 4.1.0 release and #5229.

Note for hosted ChatGPT Actions or Custom GPTs: Hosted cloud services cannot reach localhost. Place an authenticating HTTPS proxy (e.g., ngrok, Cloudflare Tunnel, or Caddy with TLS and Auth) in front of the server before connecting cloud services.

⚡ VS Code (Cline, Roo Code, GitHub Copilot Agent Mode, Continue)

Cline / Roo Code Settings (cline_mcp_settings.json):

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

Continue.dev Config (~/.continue/config.yaml):

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"

💻 Cursor & Windsurf

Add to ~/.cursor/mcp.json:

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

🐙 GitHub Copilot CLI & Workspace Agent

Add .github/mcp.json to your repository:

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

Note for Copilot Cloud Agents: Cloud code-review integrations must be configured through Repository Settings > Copilot > MCP servers instead.

❄️ Cortex Code (Snowflake / Enterprise CLI)

Add directly via the Cortex CLI:

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