mcp-server-sigma

📊 mcp-server-sigma

为你的 AI Agent 注入原生 Sigma Computing 超能力！ ⚡
企业级 Model Context Protocol（MCP）服务，提供 257 个工具，涵盖连接、工作簿、数据模型、成员、团队、部署、Webhook、多租户操作，以及可直接用于你最喜爱的 AI 助手的组合式工作流配方。

⚠️ 免责声明与安全警告

重要

社区项目免责声明
mcp-server-sigma 是一个独立的开源社区项目，与 Sigma Computing, Inc. 不存在关联、赞助、认可或支持关系。"Sigma Computing" 是 Sigma Computing, Inc. 的商标。

警告

凭据与安全须知
此服务使用适用于你所在 Sigma 组织的 API 凭据。工具可以修改工作簿、用户、团队和数据模型。

• 只读模式： 如需安全运行且避免修改风险，请设置 SIGMA_MCP_READONLY=1 或 --profile readonly（仅列出标注为 readOnlyHint=true 的 120 个工具，并拒绝所有其他调用）。
• 破坏性操作安全门： 所有单项删除工具都要求显式设置 confirm=True；未设置时不会进行任何更改，而是返回正常结果（isError: false），提示调用方使用 confirm=true 重新调用。缺少参数或参数无效时会返回工具错误（isError: true），供模型修正；其他调用失败也会如此，例如找不到成员、导出超时或批量停用模式被拒绝（参见 docs/errors.md）。若批处理工具中的所有项目均失败，则会返回 isError: true 和 "type": "batch_failed"；部分成功仍会返回正常结果，其中包含 "status": "partial_success"、<verb>_count、failed_count、results 和 errors。每个条目都包含 id、status，以及 result 或 error，并保留各工具此前返回的字段名；早期版本曾列在 results 中的失败项目也仍会保留（参见 docs/errors.md）。批量破坏性操作（admin_bulk_deactivate_members、admin_bulk_remove_team_members）会列在 full 中，但调用时会被拒绝，除非设置 SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1。
• 在部署到生产环境前，请阅读 SECURITY.md。

💡 为什么要构建此项目

Sigma Computing 有一种独特的架构不对称性，影响着自动化方式：

1. **数据模型 100% 可通过代码表示：**你可以通过编程构建数据模型、定义列、联接和 SQL 逻辑、更新 JSON 规范，并通过 API 替换数据仓库数据源。
2. **工作簿布局主要由 UI 驱动：**虽然 Sigma 已推出用于工作簿规范的 Beta 端点（/v2/workbooks/spec），但从头开始以编程方式构建布局元素仍然非常复杂。

自动化 BI 仪表板的标准做法是：
先在 Sigma UI 中构建一次布局并将其保存为模板，然后在此后始终通过编程方式实例化模板并替换数据源！ 🎨 ➡️ 🤖

我们的组合配方工具（如 workbooks_deploy_template_to_folder 和 elements_swap_workbook_sources）只需一次 MCP 工具调用，就能自动完成这一模式（如果中间步骤失败，则返回结构化的步骤进度或部分失败详情）：

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

📦 快速入门与安装

1. 通过 pip 或 uv 安装

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

或通过 Docker 运行

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

镜像的默认命令使用 stdio。若要从容器提供 Streamable HTTP 服务，请在容器内绑定 0.0.0.0 并传入令牌。不要将令牌放在命令行中（它会出现在 Shell 历史记录和 ps 输出中）：请将 SIGMA_MCP_AUTH_TOKEN 放入 .env，或者导出该变量，并使用 -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. 设置环境变量

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"

提示

请使用分配给你所在组织所在区域的 API 基础 URL。

🔌 AI 助手与 IDE 集成指南

mcp-server-sigma 可通过标准 stdio 或 streamable-http，与所有主流 AI 助手、IDE 和 CLI 工具无缝协作。

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

🛡️ 安全与防护控制

使用环境变量配置行为：

🧭 配置档

使用 --profile 或 SIGMA_MCP_PROFILE 选择配置档（默认值为 full）。每个配置档都会挂载全部五个域（workbooks、datasets、elements、workspace、admin）。任务配置档只会公开一个明确列出的工具名称清单，用于特定任务；所有配置档均可使用提示词和资源。服务器构建时会根据完整目录检查每个列出的名称，因此，未知的配置档或清单中的拼写错误都会导致启动失败，并报出 ValueError。

以下 22 个工具不属于任何任务配置档，仅在 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 和 admin_delete_translation_variant。

只读行为

• MCP 的 readOnlyHint 注解是判定工具是否为只读工具的唯一依据。每个工具都会显式声明此注解：120 个读取工具的值为 true，137 个写入工具的值为 false。没有注解或没有 readOnlyHint 的工具均视为写入工具。
• 使用 --profile readonly 或 SIGMA_MCP_READONLY=1（适用于任何配置档）时，只会列出只读工具；ReadOnlyGateMiddleware 会拒绝对任何非只读的实际工具进行调用，包括被筛选隐藏的写入工具。拒绝调用时会返回一个 isError: true 的工具结果。
• 如果某个名称不是服务器上的工具，FastMCP 会直接或通过 call_tool 返回常规的 Unknown tool 错误，因此，拼写错误绝不会被报告为遭到拦截的工具。
• 启用 Tool Search 后，网关会检查 call_tool 所包装的工具。通过 call_tool 进行读取可以正常运行，写入则会遭到拒绝。未启用 Tool Search 时，call_tool 不是服务器上的工具，因此调用它会得到 Unknown tool: 'call_tool'。
• 如果网关无法看到提供服务的服务器，就会拒绝该调用。

批量操作网关

admin_bulk_deactivate_members 和 admin_bulk_remove_team_members 已列在 full 中。除非设置 SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1，否则 admin 域防护机制会在调用时拒绝它们（isError: true），且处理程序仍会执行各自的 confirm / dry_run 安全检查。只读模式会隐藏并拒绝这些工具。

工具搜索和代码模式

默认情况下，tools/list 是扁平列表。发现功能需选择启用，且仅在 full 配置下生效：

• --enable-tool-search / SIGMA_MCP_ENABLE_TOOL_SEARCH=1 会将 tools/list 替换为 search_tools 和 call_tool。后端为 regex（默认）或 bm25（--tool-search-backend / SIGMA_MCP_TOOL_SEARCH_BACKEND）。
• --enable-code-mode / SIGMA_MCP_ENABLE_CODE_MODE=1 会挂载 FastMCP 的实验性代码模式（search、get_schema、execute）。代码模式需要使用软件包的 code-mode extra 提供沙箱（fastmcp[code-mode]，其中包含 pydantic-monty）：pip install "mcp-server-sigma[code-mode]" 或 uvx "mcp-server-sigma[code-mode]" --enable-code-mode。如果未安装该 extra，将跳过代码模式并发出警告，同时提供扁平目录。
• 同时启用两者会引发 ValueError。在其他配置下请求启用任一功能都会记录警告，并保留扁平列表。
• search_tools、search 和 get_schema 仅读取目录，并标注为 readOnlyHint=true。在只读模式下，代码模式的 execute 会被拒绝。

📊 功能与工具概览

full 配置列出 257 个工具。每个工具名称都以其所属领域开头：

如果这些数量与实时注册表中的数量不一致，scripts/check_tool_contract.py 会使 CI 失败。2 个具有批量破坏性的工具（admin_bulk_deactivate_members、admin_bulk_remove_team_members）计入 admin 的数量；除非设置 SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1，否则调用时会被拒绝。

🍳 复合工作流配方

这些高级工具将多个步骤的 API 调用序列封装为一次原子调用：

📐 MCP 2.0 提示与安全注释

每个工具都包含结构化的 MCP 提示，以协助 AI 客户端向用户征求权限：

🧮 编写 Sigma 公式

AI 模型编写 Sigma 公式时经常会幻觉出 SQL 或 Excel 函数（例如使用 ArrayAgg() 而不是 List()）。
编写任何 Sigma 公式前，请先调用内置参考工具：

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

有关完整语法详情，请参阅 docs/formulas.md。

👩‍💻 本地开发与测试

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

说明

自动漂移检查：CI 工作流（ci.yml）包含一个 check-drift 作业，每周日美国东部时间下午运行一次，也可手动触发；该作业会将客户端方法与 Sigma 实时 OpenAPI 规范进行比较。如果漂移扫描在 main 上运行并发现漂移或因错误退出，该作业会自动在仓库中创建一个 issue。若较早的设置步骤失败，则运行会失败，但不会创建 issue。

🤝 贡献与社区

欢迎贡献！请阅读 CONTRIBUTING.md 了解开发规范，阅读 SECURITY.md 了解安全问题报告方式，并阅读 CODE_OF_CONDUCT.md 了解社区准则。

📜 许可证

MIT 许可证。
版权所有 (c) 2026 Christian Claudio。

免责声明：与 Sigma Computing, Inc. 无关联，未获其赞助或认可。