使用说明

QuickSight MCP服务器

最全面的AWS QuickSight MCP服务器，具有自学习功能、图表构建器和内置QA验证。

为什么选择此服务器？

其他QuickSight MCP服务器要么是自动生成的API包装器，要么仅限于沿袭查询。该服务器从4800多条生产线库中提取，将经过战斗测试的模式包装成 55个MCP工具.

主要区别：

55个专用工具 涵盖完整的开发人员工作流程：读取、构建、编辑、验证、发布
图表生成器 从简单的参数（列+聚合）创建视觉效果——不需要原始JSON
质量保证体系 使用snapshot/diff比较任何更改前后的情况
写后验证 在每次操作中——捕捉QuickSight无声的失败
自学习引擎 跟踪使用模式并建议优化
安全生产 具有自动备份、乐观锁定、破坏性更改保护

快速开始

安装

pip install quicksight-mcp

或与紫外线:

uv pip install quicksight-mcp

配置

添加到您的MCP客户端配置（Claude Desktop、Cursor等）：

{
  "mcpServers": {
    "quicksight": {
      "command": "quicksight-mcp",
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

或者使用uvx（无需安装）：

{
  "mcpServers": {
    "quicksight": {
      "command": "uvx",
      "args": ["quicksight-mcp"],
      "env": {
        "AWS_PROFILE": "your-profile"
      }
    }
  }
}

认证

使用标准AWS凭证链：

环境变量(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
命名配置文件(AWS_PROFILE)
IAM角色（适用于EC2/Lambda）
SSO凭据

STS会自动检测帐户ID。覆盖 AWS_ACCOUNT_ID 如果需要的话。

工具参考（55个工具）

数据集（8个工具）

工具	说明
`list_datasets`	列出所有具有名称、ID和导入模式的数据集
`search_datasets`	按名称搜索数据集（不区分大小写）
`get_dataset`	获取数据集的完整元数据（列、表、导入模式）
`get_dataset_sql`	让SQL查询为数据集提供动力
`update_dataset_sql`	使用自动备份和验证更新数据集SQL
`refresh_dataset`	触发SPICE刷新
`get_refresh_status`	检查SPICE刷新进度
`list_recent_refreshes`	获取数据集的刷新历史记录

分析检查（12个工具）

工具	说明
`list_analyses`	列出所有分析及其状态
`search_analyses`	按名称搜索分析
`describe_analysis`	获取完整结构：表格、视觉效果、字段、参数、数据集
`list_visuals`	列出所有视觉效果，包括类型、标题和图纸位置
`list_calculated_fields`	列出所有带有表达式的计算字段
`get_columns_used`	获取整个分析中的列使用频率
`get_parameters`	列出所有参数声明
`get_filters`	列出所有具有范围和条件的筛选器组
`get_analysis_raw`	获取完整的原始分析定义以供检查
`verify_analysis_health`	运行全面的健康检查（状态、布局、参考）
`snapshot_analysis`	捕获当前状态作为QA的基线
`diff_analysis`	将当前状态与快照进行比较

图表生成器（5个工具）

从简单的参数创建视觉效果——不需要原始JSON。

工具	说明
`create_kpi`	从列+聚合创建KPI
`create_bar_chart`	创建包含类别+值列的条形图
`create_line_chart`	创建日期+值+粒度的折线图
`create_pivot_table`	创建包含行/值列的数据透视表
`create_table`	使用列列表创建平面表

可视化管理（5个工具）

工具	说明
`get_visual_definition`	获取任何视觉效果的完整原始定义
`add_visual`	从JSON定义中添加可视化内容（供高级使用）
`delete_visual`	使用布局清理删除视觉效果
`set_visual_title`	更新视觉对象的显示标题
`set_visual_layout`	在网格上设置视觉位置和大小

表单管理（5个工具）

工具	说明
`add_sheet`	向分析中添加新工作表
`delete_sheet`	删除工作表及其视觉效果
`rename_sheet`	重命名现有图纸
`list_sheet_visuals`	在特定表格上列出所有视觉效果
`replicate_sheet`	复制包含所有视觉效果的整个工作表（批量、单个API调用）

计算字段（4个工具）

工具	说明
`add_calculated_field`	将新的计算字段添加到分析中
`update_calculated_field`	更新计算字段的表达式
`delete_calculated_field`	删除计算字段
`get_calculated_field`	获取特定计算字段的详细信息

参数和过滤器（4个工具）

工具	说明
`add_parameter`	添加参数（字符串、整数、日期、小数）
`delete_parameter`	按名称删除参数
`add_filter_group`	添加具有作用域配置的筛选器组
`delete_filter_group`	删除筛选器组

仪表板（5个工具）

工具	说明
`list_dashboards`	列出所有仪表板
`search_dashboards`	按名称搜索仪表板
`get_dashboard_versions`	列出版本历史记录
`publish_dashboard`	从分析中发布仪表板
`rollback_dashboard`	回滚到以前的版本

备份和还原（4个工具）

工具	说明
`backup_analysis`	将分析定义备份到JSON
`backup_dataset`	将数据集定义备份到JSON
`restore_analysis`	从备份文件还原分析
`clone_analysis`	用于安全测试的克隆分析

自学（2个工具）

工具	说明
`get_learning_insights`	显示使用模式和优化建议
`get_error_patterns`	显示常见错误及其频率

开发人员工作流程

服务器支持完整的构建-验证-发布周期：

1.构建：从简单参数创建可视化

"Add a KPI showing total contracts to the SLA sheet"

create_kpi(
    analysis_id = "abc-123",
    sheet_id    = "sheet-456",
    title       = "Total Contracts",
    column      = "FLIP_TOKEN",
    aggregation = "COUNT",
    dataset_identifier = "acq_l2_flip_details"
)
→ Returns: {visual_id: "kpi_50ed988920b4", status: "UPDATE_SUCCESSFUL"}

"Add a weekly trend line chart"

create_line_chart(
    analysis_id = "abc-123",
    sheet_id    = "sheet-456",
    title       = "Weekly Contract Trend",
    date_column = "PURCHASE_AGREEMENT_COMPLETED_AT",
    value_column = "FLIP_TOKEN",
    value_aggregation = "COUNT",
    dataset_identifier = "acq_l2_flip_details",
    date_granularity = "WEEK"
)

"Add a market breakdown pivot table"

create_pivot_table(
    analysis_id = "abc-123",
    sheet_id    = "sheet-456",
    title       = "Market Breakdown",
    row_columns = "MARKET_NAME,ASSESSMENT_TYPE",
    value_columns = "FLIP_TOKEN,REVENUE",
    value_aggregations = "COUNT,SUM",
    dataset_identifier = "acq_l2_flip_details"
)

2.验证：使用快照和差异进行QA

# Before making changes -- capture baseline
snapshot_analysis("abc-123")
→ Returns: {snapshot_id: "snap_20260212_193448", visuals: 185, sheets: 20}

# Make your changes...
create_kpi(...)
create_bar_chart(...)

# After changes -- verify what changed
diff_analysis("abc-123", "snap_20260212_193448")
→ Returns: {
    visuals_added: [
      {type: "KPI", title: "Total Contracts"},
      {type: "BarChart", title: "Contracts by Market"}
    ],
    visuals_removed: [],
    visual_changes: [],
    old_visual_count: 185,
    new_visual_count: 187
  }

# Health check -- ensure nothing broke
verify_analysis_health("abc-123")
→ Returns: {
    healthy: true,
    checks: [
      {check: "analysis_status", ok: true},
      {check: "sheet_count", ok: true, count: 20},
      {check: "visual_layout_alignment", ok: true},
      {check: "calc_field_dataset_refs", ok: true}
    ]
  }

3.发布：推送到仪表板

# Publish when ready
publish_dashboard("dash-id", "abc-123", "Added KPI and bar chart for contracts")

# Rollback if something goes wrong
rollback_dashboard("dash-id", version_number=5)

其他常见工作流

更新数据集SQL：

search_datasets("WBR")                    → find dataset ID
get_dataset_sql("ds-123")                 → view current SQL
update_dataset_sql("ds-123", "new SQL")   → update with auto-backup
refresh_dataset("ds-123")                 → trigger SPICE reload
get_refresh_status("ds-123", "ing-456")   → monitor progress

复制整个工作表：

describe_analysis("abc-123")                          → find source sheet ID
replicate_sheet("abc-123", "sheet-456", "My Copy")    → copies all visuals + layouts

使用克隆进行安全测试：

clone_analysis("prod-id", "Test Copy")    → creates isolated copy
create_kpi("clone-id", ...)               → make changes on clone
verify_analysis_health("clone-id")        → verify
diff_analysis("clone-id", snapshot_id)    → review changes
[apply same changes to production]

安全生产特点

写后验证

每次写入操作都会验证其更改是否实际持久：

add_sheet 验证是否存在具有正确名称的工作表
delete_sheet 验证该表是否已实际删除
create_kpi / create_bar_chart /等等，验证视觉是否存在
set_visual_title 验证标题是否匹配
add_parameter 验证参数是否存在
replicate_sheet 验证工作表和视觉计数

这捕获了QuickSight的静默式故障，API返回 200 OK 但不应用该更改。

自动备份

每次写入操作在进行更改之前都会自动创建一个带时间戳的JSON备份。备份保存到 ~/.quicksight-mcp/backups/.

乐观锁

修改分析时，服务器会检查自上次读取以来没有其他人修改过它。防止以静默方式覆盖并发更改。

破坏性变更保护

将删除所有工作表、大多数视觉效果或大多数计算字段的更新被阻止。防止格式错误的定义导致意外数据丢失。

分析防护失败

服务器拒绝更新处于“失败”状态的分析，以防止损坏的定义发生级联故障。先从备份还原。

QuickSight限制

服务器强制执行QuickLight的每次分析20张的限制，提供清晰的错误消息，而不是神秘的API故障。

自学习引擎

服务器从您的使用模式中学习，并随着时间的推移变得更加智能。

它追踪什么

工具使用频率和顺序
常见工作流（例如，搜索->获取SQL->更新->刷新）
错误模式及其类别
操作持续时间

它暗示了什么

基于常见模式的工作流优化
对频繁访问的资源进行缓存改进
常见错误的已知修复
QuickSight特有的SQL语法陷阱

所有学习数据都存储在本地。任何地方都不会发送遥测数据。

环境变量

变量	默认值	描述
`AWS_PROFILE`	（无）	AWS命名配置文件
`AWS_REGION`	`us-east-1`	AWS区域
`AWS_ACCOUNT_ID`	（自动检测）	QuickSight帐户ID
`QUICKSIGHT_BACKUP_DIR`	`~/.quicksight-mcp/backups`	备份目录
`QUICKSIGHT_MCP_LEARNING`	`true`	启用自学习
`QUICKSIGHT_MCP_LEARNING_DIR`	`~/.quicksight-mcp/`	学习数据目录
`LOG_LEVEL`	`INFO`	日志记录级别

建筑

quicksight-mcp/
  src/quicksight_mcp/
    server.py              # FastMCP entry point, lazy dependency init
    client.py              # QuickSight API wrapper with safety features
    exceptions.py          # Structured errors
    tools/
      datasets.py          # 8 dataset tools
      analyses.py          # 12 analysis + QA tools
      visuals.py           # 10 visual + chart builder tools
      sheets.py            # 5 sheet management tools
      calculated_fields.py # 4 calculated field tools
      parameters.py        # 2 parameter tools
      filters.py           # 2 filter tools
      dashboards.py        # 5 dashboard tools
      backup.py            # 4 backup/restore tools
      learning.py          # 2 self-learning tools
    learning/
      tracker.py           # Usage pattern recording
      optimizer.py         # Recommendation engine
      knowledge.py         # Local key-value knowledge store

服务器使用 延迟初始化 --AWS客户端和学习引擎仅在第一个工具调用到达时创建，保持即时启动。

每个工具模块都公开一个 register_*_tools(mcp, get_client, get_tracker) 附加的功能 @mcp.tool FastMCP服务器实例的处理程序。

发展

git clone https://github.com/krishna-goje/quicksight-mcp.git
cd quicksight-mcp
pip install -e ".[dev]"
pytest

运行测试

# All tests
pytest

# With coverage
pytest --cov=quicksight_mcp

# Specific module
pytest tests/test_learning.py

掉毛

ruff check src/ tests/
ruff format src/ tests/

作者

克里希纳·戈耶 --员工分析工程师|人工智能增强工程

文件夹：克里希纳-戈伊图博.io
领英： linkedin.com/in/krishnagoje
github： https://krishna-goje
电子邮件：krishna19.gk@gmail.com

背景

在美国运通、Grubhub、Booking.com和Opendoor建立数据平台14年。开创了一个人工智能增强工程生态系统，将15多个企业平台与并行代理编排和自学习反馈循环连接起来。

为什么这个项目

此服务器是从经过数月日常QuickSight工作构建的4800多条生产线库中提取的。每个安全功能都是由于真实的生产事件而存在的：

自动备份 --更新一旦擦除了分析，就无法撤消
乐观锁定 --编辑同一分析的两个会话默默地相互覆盖
变更验证 --QuickSight的API退货 200 OK 但有时不会应用更改
破坏性变更保护 --格式错误的定义更新删除了实时仪表板中的所有工作表
状态保护失败 --更新失败分析导致级联损坏

开源

闪光mcp --用于AWS QuickSight管理的MCP服务器
松弛数据机器人 --具有作者/审稿人质量循环的自主数据问答机器人

贡献

欢迎捐款。请先打开一个问题，讨论您想更改什么。

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
运行测试(pytest)
提交您的更改
打开拉取请求

许可证

Apache 2.0——请参阅许可证了解详情。