{
"markdown": "# ๐ mcp-server-sigma\n\n[](https://github.com/christianclaudio/mcp-server-sigma/actions/workflows/ci.yml)\n[](https://pypi.org/project/mcp-server-sigma/)\n[](https://pypi.org/project/mcp-server-sigma/)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/christianclaudio/mcp-server-sigma)\n[](https://coderabbit.ai)\n\n> **Supercharge your AI Agents with native Sigma Computing superpowers!** โก \n> 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.\n\n---\n\n## โ ๏ธ Disclaimers & Safety Warnings\n\n> [!IMPORTANT]\n> **Community Project Disclaimer** \n> `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.\n\n> [!WARNING]\n> **Credentials & Safety Notice** \n> This server uses API credentials scoped to your Sigma organization. Tools can mutate workbooks, users, teams, and data models. \n> - **Read-Only Mode:** To run safely without mutation risk, set `SIGMA_MCP_READONLY=1` (grants 83 read-only tools). \n> - **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`. \n> - Read [SECURITY.md](https://github.com/christianclaudio/mcp-server-sigma/blob/main/SECURITY.md) before deploying to production.\n\n---\n\n## ๐ก Why This Exists\n\nSigma Computing has a unique architectural asymmetry that shapes how you automate it:\n\n1. **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.\n2. **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. \n\nThe canonical path to automated BI dashboards is: \n**Build the layout once in the Sigma UI, save it as a template, then instantiate and source-swap it programmatically forever after!** ๐จ โก๏ธ ๐ค\n\nOur 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):\n\n```mermaid\ngraph TD\n UI[\"Sigma UI\"] -->|\"1. Build Layout Once & Save\"| TPL[\"Sigma Template\"]\n Agent[\"AI Agent / LLM\"] -->|\"2. Call sigma_deploy_template_to_folder\"| MCP[\"mcp-server-sigma\"]\n MCP -->|\"POST /v2/templates/{id}/instantiate\"| API1[\"Instantiate Workbook\"]\n MCP -->|\"POST /v2/workbooks/{id}/swap_sources\"| API2[\"Swap Warehouse Sources\"]\n API2 -->|\"Delivered\"| Dest[\"Target Customer Folder\"]\n```\n\n---\n\n## ๐ฆ Quickstart & Installation\n\n### 1. Install via `pip` or `uv`\n\n```bash\npip install mcp-server-sigma\n# or with uv\nuv pip install mcp-server-sigma\n```\n\n### Or run via Docker\n\n```bash\ndocker run --rm -i --env-file .env \\\n ghcr.io/christianclaudio/mcp-server-sigma:latest\n```\n\n### 2. Set Environment Variables\n\n```bash\nexport SIGMA_CLIENT_ID=\"your-client-id\"\nexport SIGMA_CLIENT_SECRET=\"your-client-secret\"\nexport SIGMA_API_BASE_URL=\"https://api.us-a.aws.sigmacomputing.com\"\n```\n\n> [!TIP]\n> Use the API base URL assigned to your organization's region.\n\n| Region | Base URL |\n|--------|----------|\n| **AWS US East** | `https://api.us-a.aws.sigmacomputing.com` |\n| **AWS US West** | `https://aws-api.sigmacomputing.com` |\n| **AWS Canada** | `https://api.ca.aws.sigmacomputing.com` |\n| **AWS EU** | `https://api.eu.aws.sigmacomputing.com` |\n| **AWS UK** | `https://api.uk.aws.sigmacomputing.com` |\n| **AWS Australia** | `https://api.au.aws.sigmacomputing.com` |\n| **Azure US** | `https://api.us.azure.sigmacomputing.com` |\n| **Azure EU** | `https://api.eu.azure.sigmacomputing.com` |\n| **Azure Canada** | `https://api.ca.azure.sigmacomputing.com` |\n| **Azure UK** | `https://api.uk.azure.sigmacomputing.com` |\n| **Azure Australia** | `https://api.au.azure.sigmacomputing.com` |\n| **GCP US** | `https://api.sigmacomputing.com` |\n| **GCP Saudi Arabia** | `https://api.sa.gcp.sigmacomputing.com` |\n\n---\n\n## ๐ Integration Guides for AI Assistants & IDEs\n\n`mcp-server-sigma` works seamlessly with all major AI assistants, IDEs, and CLI tools via standard `stdio` or `streamable-http`.\n\n\n๐งก Claude Desktop & Claude Code
\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"sigma\": {\n \"command\": \"sigma-mcp\",\n \"env\": {\n \"SIGMA_CLIENT_ID\": \"your-client-id\",\n \"SIGMA_CLIENT_SECRET\": \"your-client-secret\",\n \"SIGMA_API_BASE_URL\": \"https://api.us-a.aws.sigmacomputing.com\"\n }\n }\n }\n}\n```\n\nFor **Claude Code CLI**:\n```bash\nclaude mcp add sigma -- sigma-mcp\n```\n \n\n\nโ Google Antigravity & Gemini CLI
\n\nAdd to your project's `.agents/mcp_config.json` (or global `~/.gemini/config/mcp_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"sigma\": {\n \"command\": \"sigma-mcp\",\n \"args\": [],\n \"env\": {\n \"SIGMA_CLIENT_ID\": \"your-client-id\",\n \"SIGMA_CLIENT_SECRET\": \"your-client-secret\",\n \"SIGMA_API_BASE_URL\": \"https://api.us-a.aws.sigmacomputing.com\"\n }\n }\n }\n}\n```\n \n\n\n๐ค OpenAI Codex & Local HTTP Clients
\n\nRun in network transport mode (Streamable HTTP) for local CLI & agent extensions:\n\n```bash\n# Source environment variables from a protected file or secret manager\nsource .env\n\n# Launch server on HTTP localhost port 8000 for local clients\nsigma-mcp --transport streamable-http --host 127.0.0.1 --port 8000\n```\n\nPoint your local Codex / HTTP SSE client to `http://127.0.0.1:8000/sse`.\n\n*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.\n \n\n\nโก VS Code (Cline, Roo Code, GitHub Copilot Agent Mode, Continue)
\n\n#### Cline / Roo Code Settings (`cline_mcp_settings.json`):\n```json\n{\n \"mcpServers\": {\n \"sigma\": {\n \"command\": \"sigma-mcp\",\n \"env\": {\n \"SIGMA_CLIENT_ID\": \"your-client-id\",\n \"SIGMA_CLIENT_SECRET\": \"your-client-secret\",\n \"SIGMA_API_BASE_URL\": \"https://api.us-a.aws.sigmacomputing.com\"\n }\n }\n }\n}\n```\n\n#### Continue.dev Config (`~/.continue/config.yaml`):\n```yaml\nmcpServers:\n - name: sigma\n command: sigma-mcp\n env:\n SIGMA_CLIENT_ID: \"your-client-id\"\n SIGMA_CLIENT_SECRET: \"your-client-secret\"\n SIGMA_API_BASE_URL: \"https://api.us-a.aws.sigmacomputing.com\"\n```\n \n\n\n๐ GitHub Copilot CLI & Workspace Agent
\n\nAdd `.github/mcp.json` to your repository:\n\n```json\n{\n \"mcpServers\": {\n \"sigma\": {\n \"type\": \"local\",\n \"command\": \"sigma-mcp\",\n \"env\": {\n \"SIGMA_CLIENT_ID\": \"${COPILOT_MCP_SIGMA_CLIENT_ID}\",\n \"SIGMA_CLIENT_SECRET\": \"${COPILOT_MCP_SIGMA_CLIENT_SECRET}\",\n \"SIGMA_API_BASE_URL\": \"https://api.us-a.aws.sigmacomputing.com\",\n \"SIGMA_MCP_READONLY\": \"1\"\n },\n \"tools\": [\"sigma_get_workbook\", \"sigma_list_workbooks\", \"sigma_get_data_model\"]\n }\n }\n}\n```\n\n*Note for Copilot Cloud Agents:* Cloud code-review integrations must be configured through Repository Settings > Copilot > MCP servers instead.\n \n\n\nโ๏ธ Cortex Code (Snowflake / Enterprise CLI)
\n\nAdd directly via the Cortex CLI:\n\n```bash\ncortex mcp add sigma-tools -- sigma-mcp\n```\n \n\n---\n\n## ๐ก๏ธ Safety & Security Controls\n\nConfigure behavior using environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SIGMA_CLIENT_ID` | *Required* | Your Sigma API client ID. |\n| `SIGMA_CLIENT_SECRET` | *Required* | Your Sigma API client secret. |\n| `SIGMA_API_BASE_URL` | *Required* | Region-specific Sigma API host URL. |\n| `SIGMA_MCP_PROFILE` | `full` | Tool registration subset: `core` (38 tools), `admin` (54), `embed` (57), `full` (155). |\n| `SIGMA_MCP_READONLY` | `0` | Set `1` to register **only** read-only tools (83 tools). Models cannot alter org state. |\n| `SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE` | `0` | Set `1` to enable bulk deactivate/remove operations (`sigma_bulk_deactivate_members`, `sigma_bulk_remove_team_members`) (157 total). |\n| `SIGMA_ALLOWED_TENANTS` | `\"\"` | Comma-separated allowlist of tenant org IDs permitted for RFC 8693 token exchange. |\n| `SIGMA_STRICT_TENANT_ALLOWLIST` | `0` | Set `1` to fail closed (HTTP 403) if a tenant request is made without an explicit allowlist entry. |\n| `SIGMA_MCP_LOG_FORMAT` | `text` | Set `json` for structured JSON logging with duration metrics (`duration_ms`). |\n\n---\n\n## ๐ Feature & Tool Summary\n\nThe server registers **155 tools by default** across the following domain modules:\n\n| Domain | Tools | Key Capabilities |\n|--------|-------|------------------|\n| **Workbooks** | 33 | CRUD, pages, elements, columns, queries, sources, swap, lineage, exports, materializations, bookmarks, tags, grants, embeds |\n| **Reports** | 13 | CRUD, elements, queries, lineage, exports, schedules, sources, duplication |\n| **Data Models** | 10 | CRUD, JSON spec inspection & editing, elements, columns, sources, swap, lineage, tags |\n| **Members** | 10 | List, get, create, update, deactivate, teams, bulk deactivate, email change, onboarding |\n| **Teams** | 10 | List, get, create, delete, members, bulk assign/remove, user attributes |\n| **Connections** | 7 | List, get, schema sync, connectivity test, columns, grants |\n| **Multi-Tenant** | 6 | List tenants, tenant info, capabilities, cross-tenant connection sync |\n| **Deployments** | 6 | List, get, create, add documents, archive |\n| **Templates** | 6 | List, get, instantiate, save from workbook, swap sources, shared templates |\n| **Workspaces** | 6 | List, get, create, delete, grants |\n| **User Attributes** | 9 | CRUD, user/team/tenant value assignments |\n| **Webhooks** | 6 | Webhook subscription management, payload signature validation, event history |\n| **Grants** | 5 | Access control lists, workbook/workspace/connection grants |\n| **Files & Folders** | 4 | Inode search, create folder, update, delete |\n| **Tags** | 4 | List, create, tag workbook, tag data model |\n| **Reference** | 4 | `sigma_api_capabilities`, `sigma_formula_pitfalls`, `sigma_search_docs`, `sigma_get_doc_page` |\n| **Composite Recipes** | 14 | High-level multi-step workflow recipes |\n\n*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.*\n\n---\n\n## ๐ณ Composite Workflow Recipes\n\nThese high-level tools bundle multi-step API sequences into a single atomic call:\n\n| Recipe Tool | What It Does |\n|-------------|--------------|\n| `sigma_deploy_template_to_folder` | Instantiates a template & swaps warehouse sources in 1 call |\n| `sigma_materialize_and_wait` | Triggers a data materialization and polls until complete with timeout |\n| `sigma_onboard_member` | Atomically creates a member and assigns them to multiple teams |\n| `sigma_bulk_assign_team_members` | Batch-adds $N$ members to a team in a single request |\n| `sigma_bulk_remove_team_members` | Resolves member emails and batch-removes them from a team |\n| `sigma_bulk_deactivate_members` | Regex-matches members, generates dry-run report, and deactivates |\n| `sigma_bulk_sync_tenant_connections` | Performs RFC 8693 token exchange per tenant to sync all connections |\n| `sigma_copy_workbook_to_member` | Duplicates a workbook directly into a user's home folder |\n| `sigma_promote_workbook` | Tags a workbook for version promotion (creates tag if missing) |\n| `sigma_export_and_download` | Exports workbook/element, handles 204 polling, returns final content |\n| `sigma_sync_all_tables_in_schema` | Syncs an entire database.schema path across Sigma connections |\n| `sigma_reassign_workbook_ownership` | Bulk-transfers workbook ownership from one member email to another |\n\n---\n\n## ๐ MCP 2.0 Hints & Safety Annotations\n\nEvery tool includes structured MCP hints to assist AI clients with user permission prompts:\n\n| Annotation | Count | Meaning |\n|------------|-------|---------|\n| `readOnlyHint=true` | 83 | Indicates intended non-mutation; clients may still require explicit user approval |\n| `destructiveHint=true` | 16 | Deletes, deactivates, or revokes; clients should prompt |\n| `idempotentHint=true` | 8 | Safe to retry; same input = same outcome |\n| `openWorldHint=true` | 155 | All tools hit an external API |\n\n---\n\n## ๐งฎ Writing Sigma Formulas\n\nAI models frequently hallucinate SQL or Excel functions when writing Sigma formulas (e.g. using `ArrayAgg()` instead of `List()`). \nBefore writing any Sigma formula, call the built-in reference tool:\n\n```bash\n# Model prompt helper\nUse tool `sigma_formula_pitfalls` to check formula syntax rules.\n```\n\nSee [docs/formulas.md](https://github.com/christianclaudio/mcp-server-sigma/blob/main/docs/formulas.md) for full syntax details.\n\n---\n\n## ๐ฉโ๐ป Local Development & Testing\n\n```bash\n# Install dev tools\npip install -e \".[dev]\"\n\n# Run full test suite with 100% statement line coverage enforcement\npytest --cov=src/sigma_mcp --cov-fail-under=100 --cov-report=term-missing\n\n# Run OpenAPI drift check\npython scripts/check_openapi_drift.py\n\n# Run MCP tool contract validation\npython scripts/check_tool_contract.py\n\n# Code formatting & type checking\nruff check src/\nruff format --check .\nmypy --strict src/\n```\n\n> [!NOTE]\n> **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.\n\n---\n\n## ๐ค Contributing & Community\n\nContributions are welcome! Please read [CONTRIBUTING.md](https://github.com/christianclaudio/mcp-server-sigma/blob/main/CONTRIBUTING.md) for development rules, [SECURITY.md](https://github.com/christianclaudio/mcp-server-sigma/blob/main/SECURITY.md) for security reporting, and [CODE_OF_CONDUCT.md](https://github.com/christianclaudio/mcp-server-sigma/blob/main/CODE_OF_CONDUCT.md) for community standards.\n\n---\n\n## ๐ License\n\n[MIT License](https://github.com/christianclaudio/mcp-server-sigma/blob/main/LICENSE). \nCopyright (c) 2026 Christian Claudio.\n\n*Disclaimer: Not affiliated with, sponsored by, or endorsed by Sigma Computing, Inc.*\n\n\n",
"bytes": 15761,
"sha": "6e52081d691e7bdc478dfecd175e29c1db08ff811307165d79bfd052861067fe",
"repo_slug": "christianclaudio/mcp-server-sigma",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_christianclaudio_sigma_7df7595c/readme"
}