Redshift Utils MCP

🚀 Redshift Utils MCP Server

本项目实现了一个专门用于与亚马逊Redshift数据库进行交互的模型上下文协议（MCP）服务器。它架起了大语言模型（LLMs）或AI助手（如Claude、Cursor中的助手或自定义应用程序）与Redshift数据仓库之间的桥梁，实现了安全、标准化的数据访问和交互。用户可以使用自然语言或AI驱动的提示来查询数据、了解数据库结构以及执行监控/诊断操作。该服务器适用于希望以结构化和安全的方式将LLM功能直接集成到其亚马逊Redshift数据环境中的开发者、数据分析师或团队。

🚀 快速开始

本服务器主要用于连接大语言模型或AI助手与亚马逊Redshift数据库，实现数据交互。你可以按照以下步骤进行配置和使用：

1. 确保满足先决条件。
2. 完成配置，设置必要的环境变量。
3. 根据不同的使用场景，参考使用方法进行连接和操作。

✨ 主要特性

• ✨ 安全的Redshift连接（通过数据API）：使用Boto3通过AWS Redshift数据API连接到你的亚马逊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数据API客户端使用参数化查询，以降低SQL注入风险。
• 🧩 标准化MCP接口：遵循模型上下文协议规范，可与兼容的客户端（如Claude Desktop、Cursor IDE、自定义应用程序）无缝集成。

📦 安装指南

先决条件

软件

• Python 3.8+
• uv（推荐的包管理器）
• Git（用于克隆仓库）

基础设施与访问权限

• 访问亚马逊Redshift集群。
• 具有使用Redshift数据API（redshift-data:*）和访问指定Secrets Manager机密（secretsmanager:GetSecretValue）权限的AWS账户。
• 一个Redshift用户账户，其凭证存储在AWS Secrets Manager中。该用户需要在Redshift中具有执行此服务器启用的操作所需的权限（例如，CONNECT到数据库、在目标表上执行SELECT操作、在相关系统视图（如pg_class、pg_namespace、svv_all_schemas、svv_tables、svv_table_info）上执行SELECT操作）。强烈建议使用具有最小权限原则的角色。请参阅安全注意事项。

凭证

你的Redshift连接详细信息通过AWS Secrets Manager进行管理，服务器使用Redshift数据API进行连接。你需要：

• Redshift集群标识符。
• 集群内的数据库名称。
• 包含数据库凭证（用户名和密码）的AWS Secrets Manager机密的ARN。
• 集群和机密所在的AWS区域。
• 可选的AWS配置文件名称（如果不使用默认凭证/区域）。

这些详细信息将通过环境变量进行配置，具体请参阅配置部分。

配置

设置环境变量： 本服务器需要以下环境变量才能通过AWS数据API连接到你的Redshift集群。你可以直接在shell中设置这些变量，使用systemd服务文件、Docker环境文件，或者在项目根目录中创建一个.env文件（如果使用支持从.env文件加载的工具，如uv或python-dotenv）。

使用shell导出的示例

export REDSHIFT_CLUSTER_ID="your-cluster-id"
export REDSHIFT_DATABASE="your_database_name"
export REDSHIFT_SECRET_ARN="arn:aws:secretsmanager:us-east-1:123456789012:secret:your-redshift-secret-XXXXXX"
export AWS_REGION="us-east-1" # 或 AWS_DEFAULT_REGION
# export AWS_PROFILE="your-aws-profile-name" # 可选

.env文件示例（请参阅.env.example）

# Redshift MCP服务器配置的.env文件
# 如果该文件包含机密信息，请确保不要将其提交到版本控制。将其添加到.gitignore中。

REDSHIFT_CLUSTER_ID="your-cluster-id"
REDSHIFT_DATABASE="your_database_name"
REDSHIFT_SECRET_ARN="arn:aws:secretsmanager:us-east-1:123456789012:secret:your-redshift-secret-XXXXXX"
AWS_REGION="us-east-1" # 或 AWS_DEFAULT_REGION
# AWS_PROFILE="your-aws-profile-name" # 可选

必需变量表

注意：确保Boto3使用的AWS凭证（通过环境、配置文件或IAM角色）具有访问指定REDSHIFT_SECRET_ARN和使用Redshift数据API（redshift-data:*）的权限。

💻 使用示例

与Claude Desktop / Anthropic Console连接

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

{
  "mcpServers": {
    "redshift-utils-mcp": {
      "command": "uvx",
      "args": ["redshift-utils-mcp"],
      "env": {
        "REDSHIFT_CLUSTER_ID":"your-cluster-id",
        "REDSHIFT_DATABASE":"your_database_name",
        "REDSHIFT_SECRET_ARN":"arn:aws:secretsmanager:...",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

与Claude Code CLI连接

使用Claude CLI添加服务器配置：

claude mcp add redshift-utils-mcp \
  -e REDSHIFT_CLUSTER_ID="your-cluster-id" \
  -e REDSHIFT_DATABASE="your_database_name" \
  -e REDSHIFT_SECRET_ARN="arn:aws:secretsmanager:..." \
  -e AWS_REGION="us-east-1" \
  -- uvx redshift-utils-mcp

与Cursor IDE连接

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

可用的MCP资源

在进行请求时，请将{script_path}和{schema_name}替换为实际值。模式/表的可访问性取决于通过REDSHIFT_SECRET_ARN配置的Redshift用户的权限。

可用的MCP工具

📚 详细文档

待办事项

• [ ] 改进提示选项
• [ ] 增加对更多凭证方法的支持
• [ ] 增加对Redshift Serverless的支持

贡献

欢迎贡献代码！请遵循以下指南。

• 查找/报告问题：查看GitHub问题页面，了解现有的错误或功能请求。如有需要，随时打开一个新问题。

安全考虑

通过MCP服务器提供数据库访问时，安全至关重要。请考虑以下几点： 🔒 凭证管理：此服务器通过Redshift数据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 SDK构建。
• 利用AWS Python SDK（Boto3）与亚马逊Redshift数据API进行交互。
• 许多诊断SQL脚本改编自优秀的awslabs/amazon-redshift-utils仓库。