Redshift Utils MCP Server

Redshift Utils MCP 服务

概述

本项目实现了一个专为与 Amazon Redshift 数据库交互而设计的模型上下文协议（MCP）服务。

它在大模型（LLM）或 AI 助手（例如 Claude、Cursor 中的助手或自定义应用）与您的 Redshift 数据仓库之间搭建桥梁，实现安全、标准化的数据访问与交互。用户可以通过自然语言或 AI 驱动的提示词查询数据、了解数据库结构，并执行监控和诊断操作。

此服务面向希望以结构化、安全的方式将大模型能力直接集成到 Amazon Redshift 数据环境中的开发者、数据分析师或团队。

目录

• Redshift Utils MCP 服务
  • 概述
  • 目录
  • 功能
  • 先决条件
  • 安装
    • 从 PyPI 安装（推荐）
    • 从源代码安装
  • 配置
  • 使用方法
    • 连接 Claude Desktop / Anthropic Console：
    • 连接 Claude Code CLI：
    • 连接 Cursor IDE：
    • 可用的 MCP 资源
    • 可用的 MCP 工具
  • 待办事项
  • 参考资料

功能

• ✨ 安全连接 Redshift（通过 Data API）： 通过 Boto3 使用 AWS Redshift Data API 连接到 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 接口： 遵循模型上下文协议规范，可与兼容的客户端（例如 Claude Desktop、Cursor IDE、自定义应用程序）无缝集成。

前提条件

软件：

• Python 3.10+
• uv（推荐的包管理器）或 pip

基础设施与访问权限：

• 可访问 Amazon Redshift 集群。
• 拥有具备 Redshift Data 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 Data API 连接。你需要：

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

这些信息将通过环境变量配置，详情请参阅配置部分。

安装

从 PyPI 安装（推荐）

安装 Redshift Utils MCP Server 最简单的方式是直接从 PyPI 安装：

# Using pip
pip install redshift-utils-mcp

# Using uv (recommended)
uv pip install redshift-utils-mcp

从源代码安装

或者，你也可以从源代码仓库安装：

# Clone the repository
git clone https://github.com/vinodismyname/redshift-utils-mcp.git
cd redshift-utils-mcp

# Install using uv (recommended)
uv sync

# Or install using pip
pip install -e .

配置

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

使用 shell export 的示例：

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" # Or AWS_DEFAULT_REGION
# export AWS_PROFILE="your-aws-profile-name" # Optional

.env 文件示例（参见 .env.example）：

# .env file for Redshift MCP Server configuration
# Ensure this file is NOT committed to version control if it contains secrets. Add it to .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" # Or AWS_DEFAULT_REGION
# AWS_PROFILE="your-aws-profile-name" # Optional

必需变量表：

变量名称	必需	描述	示例值
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 区域时，可替代 AWS_REGION 使用。	us-west-2
AWS_PROFILE	否	要从凭证文件（~/.aws/...）中使用的 AWS 配置文件名称。	my-redshift-profile

注意：请确保 Boto3 使用的 AWS 凭证（通过环境变量、配置文件或 IAM 角色提供）有权限访问指定的 REDSHIFT_SECRET_ARN 并使用 Redshift Data API（redshift-data:*）。

使用

安装后，你可以直接从命令行运行该服务：

# If installed from PyPI
redshift-utils-mcp

# Or using uvx (no installation required)
uvx redshift-utils-mcp

连接 Claude Desktop / Anthropic Console：

将以下配置块添加到你的 mcp.json 文件中：

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

资源 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 的支持

参考资料

• 本项目大量依赖 Model Context Protocol specification。
• 使用 Model Context Protocol 提供的官方 MCP SDK 构建。
• 使用 AWS SDK for Python（Boto3）与 Amazon Redshift Data API 交互。
• 许多诊断 SQL 脚本改编自优秀的 awslabs/amazon-redshift-utils 仓库。