🚀 Redshift Utils MCP Server
本项目实现了一个专门用于与亚马逊Redshift数据库进行交互的模型上下文协议（MCP）服务器。它架起了大语言模型（LLMs）或AI助手（如Claude、Cursor中的助手或自定义应用程序）与Redshift数据仓库之间的桥梁，实现了安全、标准化的数据访问和交互。用户可以使用自然语言或AI驱动的提示来查询数据、了解数据库结构以及执行监控/诊断操作。该服务器适用于希望以结构化和安全的方式将LLM功能直接集成到其亚马逊Redshift数据环境中的开发者、数据分析师或团队。
🚀 快速开始
本服务器主要用于连接大语言模型或AI助手与亚马逊Redshift数据库，实现数据交互。你可以按照以下步骤进行配置和使用：
- 确保满足先决条件。
- 完成配置，设置必要的环境变量。
- 根据不同的使用场景，参考使用方法进行连接和操作。
✨ 主要特性
- ✨ 安全的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" # 可选
必需变量表
| 变量名 | 是否必需 | 描述 | 示例值 |
|---|---|---|---|
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 |
是 | 数据API和Secrets Manager的AWS区域。 | us-east-1 |
AWS_DEFAULT_REGION |
否 | 用于指定AWS区域的AWS_REGION的替代方案。 |
us-west-2 |
AWS_PROFILE |
否 | 要从你的凭证文件（~/.aws/...）中使用的AWS配置文件名称。 | my-redshift-profile |
注意：确保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连接
- 使用使用/快速入门部分中的说明在本地启动MCP服务器。
- 在Cursor中，打开命令面板（Cmd/Ctrl + Shift + P）。
- 输入“Connect to MCP Server”或导航到MCP设置。
- 添加一个新的服务器连接。
- 选择
stdio传输类型。 - 输入启动服务器所需的命令和参数（
uvx run redshift_utils_mcp）。确保运行命令时所需的任何环境变量都可用。 - 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数据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问题页面，了解现有的错误或功能请求。如有需要，随时打开一个新问题。
安全考虑
通过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仓库。