首页/数据库/redshift-utils-mcp

redshift-utils-mcp

查看源码
vinodismyname
2025-5-12
Words 2121Read Time≈ 6 min
Score:90

实现MCP服务器，支持AI助手通过AWS Data API安全访问Amazon Redshift数据库。

AI助手MCP服务器
Python

Redshift Utils MCP Server

概述

本项目实现了一个专门用于与 Amazon Redshift 数据库交互的 Model Context Protocol (MCP) 服务器。它充当大型语言模型 (LLMs) 或 AI 助手（如 Claude、Cursor 或自定义应用程序）与 Redshift 数据仓库之间的桥梁，支持安全、标准化的数据访问和交互。用户可以通过自然语言或 AI 驱动的提示查询数据、理解数据库结构，并执行监控和诊断操作。
该服务器面向希望将 LLM 功能直接集成到 Amazon Redshift 数据环境中的开发者、数据分析师或团队，提供结构化和安全的方式。

目录

  • Redshift Utils MCP Server
    • 概述
    • 目录
    • 功能
    • 先决条件
    • 配置
    • 使用
      • 与 Claude Desktop / Anthropic Console 连接
      • 与 Cursor IDE 连接
      • 可用的 MCP 资源
      • 可用的 MCP 工具
    • 待办事项
    • 贡献
    • 许可证
    • 参考资料

功能

  • ✨ 安全的 Redshift 连接（通过 Data API）： 使用 AWS Redshift Data API 通过 Boto3 连接到 Amazon Redshift 集群，并通过环境变量安全地管理 AWS Secrets Manager 中的凭证。
  • 🔍 模式发现： 提供 MCP 资源，用于列出指定模式中的模式和表。
  • 📊 元数据与统计信息： 提供工具 (handle_inspect_table) 以收集详细的表元数据、统计信息（如大小、行数、倾斜、统计信息陈旧度）和维护状态。
  • 📝 只读查询执行： 提供安全的 MCP 工具 (handle_execute_ad_hoc_query) 以执行针对 Redshift 数据库的任意 SELECT 查询，支持基于 LLM 请求的数据检索。
  • 📈 查询性能分析： 包括工具 (handle_diagnose_query_performance) 以检索和分析特定查询 ID 的执行计划、指标和历史数据。
  • 🔍 表检查： 提供工具 (handle_inspect_table) 以对表进行全面的检查，包括设计、存储、健康状态和使用情况。
  • 🩺 集群健康检查： 提供工具 (handle_check_cluster_health) 以使用各种诊断查询对集群进行基本或全面的健康评估。
  • 🔒 锁诊断： 提供工具 (handle_diagnose_locks) 以识别和报告当前的锁争用和阻塞会话。
  • 📊 工作负载监控： 包括工具 (handle_monitor_workload) 以分析指定时间窗口内的集群工作负载模式，涵盖 WLM、顶级查询和资源使用情况。
  • 📝 DDL 检索： 提供工具 (handle_get_table_definition) 以检索指定表的 SHOW TABLE 输出（DDL）。
  • 🛡️ 输入净化： 在适用的情况下，通过 Boto3 Redshift Data API 客户端使用参数化查询，以降低 SQL 注入风险。
  • 🧩 标准化的 MCP 接口： 遵循 Model Context Protocol 规范，与兼容的客户端（如 Claude Desktop、Cursor IDE、自定义应用程序）无缝集成。

先决条件

软件：
  • Python 3.8+
  • uv（推荐的包管理器）
  • Git（用于克隆仓库）
基础设施与访问：
  • 访问 Amazon Redshift 集群。
  • 具有使用 Redshift Data API (redshift-data:*) 和访问指定 Secrets Manager 密钥 (secretsmanager:GetSecretValue) 权限的 AWS 账户。
  • 一个 Redshift 用户账户，其凭证存储在 AWS Secrets Manager 中。该用户需要在 Redshift 中具有执行服务器启用的操作所需的权限（例如，CONNECT 到数据库，SELECT 目标表，SELECT 相关系统视图，如 pg_class、pg_namespace、svv_all_schemas、svv_tables、svv_table_info）。强烈建议使用最小权限原则的角色。请参阅 安全注意事项。
凭证：
您的 Redshift 连接详细信息通过 AWS Secrets Manager 管理，服务器使用 Redshift Data API 连接。您需要：
  • Redshift 集群标识符。
  • 集群中的数据库名称。
  • 包含数据库凭证（用户名和密码）的 AWS Secrets Manager 密钥的 ARN。
  • 集群和密钥所在的 AWS 区域。
  • 可选地，如果不是使用默认凭证/区域，则需要 AWS 配置文件名称。
这些详细信息将通过环境变量进行配置，详见 配置 部分。

配置

设置环境变量： 此服务器需要以下环境变量以通过 AWS Data API 连接到您的 Redshift 集群。您可以直接在 shell 中设置这些变量，使用 systemd 服务文件、Docker 环境文件，或在项目根目录中创建 .env 文件（如果使用支持从 .env 加载的工具，如 uv 或 python-dotenv）。
使用 shell export 的示例：
示例 .env 文件（见 .env.example）：
所需变量表：
变量名称
必填
描述
示例值
REDSHIFT_CLUSTER_ID
是
您的 Redshift 集群标识符。
my-redshift-cluster
REDSHIFT_DATABASE
是
要连接的数据库名称。
mydatabase
REDSHIFT_SECRET_ARN
是
用于 Redshift 凭证的 AWS Secrets Manager ARN。
arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret-abcdef
AWS_REGION
是
Data API 和 Secrets Manager 的 AWS 区域。
us-east-1
AWS_DEFAULT_REGION
否
用于指定 AWS 区域的替代变量。
us-west-2
AWS_PROFILE
否
从您的凭证文件 (~/.aws/...) 中使用的 AWS 配置文件名称。
my-redshift-profile
注意：确保 Boto3 使用的 AWS 凭证（通过环境、配置文件或 IAM 角色）具有访问指定 REDSHIFT_SECRET_ARN 和使用 Redshift Data API (redshift-data:*) 的权限。

使用

与 Claude Desktop / Anthropic Console 连接：

将以下配置块添加到您的 mcp.json 文件中。根据您的安装方法和设置调整 command、args、env 和 workingDirectory。

与 Cursor IDE 连接：

  1. 使用 使用 / 快速入门 部分中的说明在本地启动 MCP 服务器。
  1. 在 Cursor 中，打开命令面板 (Cmd/Ctrl + Shift + P)。
  1. 输入 "Connect to MCP Server" 或导航到 MCP 设置。
  1. 添加一个新的服务器连接。
  1. 选择 stdio 传输类型。
  1. 输入启动服务器所需的命令和参数 (uvx run redshift_utils_mcp)。确保命令所需的任何环境变量都可用。
  1. Cursor 应检测到服务器及其可用的工具/资源。

可用的 MCP 资源

资源 URI 模式
描述
示例 URI
/scripts/{script_path}
从服务器的 sql_scripts 目录中检索 SQL 脚本文件的原始内容。
/scripts/health/disk_usage.sql
redshift://schemas
列出连接数据库中所有可访问的用户定义模式。
redshift://schemas
redshift://wlm/configuration
检索当前工作负载管理 (WLM) 配置详细信息。
redshift://wlm/configuration
redshift://schema/{schema_name}/tables
列出指定 {schema_name} 中所有可访问的表和视图。
redshift://schema/public/tables
在发出请求时，将 {script_path} 和 {schema_name} 替换为实际值。模式和表的可访问性取决于通过 REDSHIFT_SECRET_ARN 配置的 Redshift 用户的权限。

可用的 MCP 工具

工具名称
描述
关键参数（必填*）
示例调用
handle_check_cluster_health
使用一组诊断 SQL 脚本对 Redshift 集群进行健康评估。
level（可选），time_window_days（可选）
use_mcp_tool("redshift-admin", "handle_check_cluster_health", {"level": "full"})
handle_diagnose_locks
识别集群中的活动锁争用和阻塞会话。
min_wait_seconds（可选）
use_mcp_tool("redshift-admin", "handle_diagnose_locks", {"min_wait_seconds": 10})
handle_diagnose_query_performance
分析特定查询的执行性能，包括计划、指标和历史数据。
query_id*
use_mcp_tool("redshift-admin", "handle_diagnose_query_performance", {"query_id": 12345})
handle_execute_ad_hoc_query
通过 Redshift Data API 执行用户提供的任意 SQL 查询。设计为应急方案。
sql_query*
use_mcp_tool("redshift-admin", "handle_execute_ad_hoc_query", {"sql_query": "SELECT ..."})
handle_get_table_definition
检索特定表的 DDL（数据定义语言）语句 (SHOW TABLE)。
schema_name, table_name
use_mcp_tool("redshift-admin", "handle_get_table_definition", {"schema_name": "public", ...})
handle_inspect_table
检索有关特定 Redshift 表的详细信息，涵盖设计、存储、健康状态和使用情况。
schema_name, table_name
use_mcp_tool("redshift-admin", "handle_inspect_table", {"schema_name": "analytics", ...})
handle_monitor_workload
使用各种诊断脚本分析指定时间窗口内的集群工作负载模式。
time_window_days（可选），top_n_queries（可选）
use_mcp_tool("redshift-admin", "handle_monitor_workload", {"time_window_days": 7})

待办事项

改进提示选项
添加对更多凭证方法的支持
添加对 Redshift Serverless 的支持

贡献

欢迎贡献！请遵循以下指南。
查找/报告问题：查看 GitHub Issues 页面以获取现有的错误或功能请求。如果需要，请随时打开一个新问题。
安全性在通过 MCP 服务器提供数据库访问时至关重要。请考虑以下事项：
🔒 凭证管理： 此服务器通过 Redshift Data API 使用 AWS Secrets Manager，这比将凭证直接存储在环境变量或配置文件中更安全。确保 Boto3 使用的 AWS 凭证（通过环境、配置文件或 IAM 角色）得到安全管理，并具有最低必要的权限。切勿将您的 AWS 凭证或包含机密的 .env 文件提交到版本控制。
🛡️ 最小权限原则： 配置其凭证存储在 AWS Secrets Manager 中的 Redshift 用户，仅授予服务器预期功能所需的最低权限。例如，如果只需要读取访问权限，则仅授予对必要模式/表的 CONNECT 和 SELECT 权限，以及对所需系统视图的 SELECT 权限。避免使用高度特权的用户，如 admin 或集群超级用户。
有关创建受限 Redshift 用户和管理权限的指南，请参阅官方文档 (https://docs.aws.amazon.com/redshift/latest/mgmt/security.html)。

许可证

此项目根据 MIT 许可证授权。详情请参阅 (LICENSE) 文件。

参考资料

上一篇
mcp
下一篇
rcs_quikmail
Catalog