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倉庫。