Redshift Utils MCP

🚀 Redshift Utils MCP Server

このプロジェクトは、Amazon Redshiftデータベースとのやり取りを目的としたModel Context Protocol (MCP)サーバーを実装しています。Large Language Models (LLMs)やAIアシスタント（Claude、Cursor、またはカスタムアプリケーションなど）とRedshiftデータウェアハウスの間のギャップを埋め、安全で標準化されたデータアクセスとやり取りを可能にします。これにより、ユーザーは自然言語またはAIによるプロンプトを使用して、データをクエリし、データベース構造を理解し、監視/診断操作を実行できます。

🚀 クイックスタート

このサーバーは、開発者、データアナリスト、またはチームが、構造化された安全な方法でLLM機能をAmazon Redshiftデータ環境に直接統合するために使用できます。

✨ 主な機能

• ✨ 安全なRedshift接続（Data API経由）: Boto3を介してAWS Redshift Data APIを使用してAmazon Redshiftクラスターに接続し、環境変数を介して安全に管理された資格情報をAWS Secrets Managerから利用します。
• 🔍 スキーマ探索: 指定されたスキーマ内のスキーマとテーブルをリストするMCPリソースを公開します。
• 📊 メタデータと統計情報: 詳細なテーブルメタデータ、統計情報（サイズ、行数、スキュー、統計の古さなど）、およびメンテナンス状態を収集するツール (handle_inspect_table) を提供します。
• 📝 読み取り専用クエリ実行: Redshiftデータベースに対して任意のSELECTクエリを実行する安全なMCPツール (handle_execute_ad_hoc_query) を提供し、LLMの要求に基づいたデータ取得を可能にします。
• 📈 クエリパフォーマンス分析: 特定のクエリIDの実行プラン、メトリック、および履歴データを取得して分析するツール (handle_diagnose_query_performance) を含みます。
• 🔍 テーブル検査: テーブルの設計、ストレージ、健全性、および使用状況を包括的に検査するツール (handle_inspect_table) を提供します。
• 🩺 クラスター健全性チェック: さまざまな診断クエリを使用して、クラスターの基本的または完全な健全性評価を実行するツール (handle_check_cluster_health) を提供します。
• 🔒 ロック診断: 現在のロック競合とブロッキングセッションを特定して報告するツール (handle_diagnose_locks) を提供します。
• 📊 ワークロード監視: 時間枠内のクラスターワークロードパターンを分析するツール (handle_monitor_workload) を含み、WLM、トップクエリ、およびリソース使用状況をカバーします。
• 📝 DDL取得: 指定されたテーブルの SHOW TABLE 出力 (DDL) を取得するツール (handle_get_table_definition) を提供します。
• 🛡️ 入力サニタイズ: 該当する場合、Boto3 Redshift Data APIクライアントを介したパラメータ化クエリを利用して、SQLインジェクションリスクを軽減します。
• 🧩 標準化されたMCPインターフェース: 互換性のあるクライアント（Claude Desktop、Cursor IDE、カスタムアプリケーションなど）とのシームレスな統合のために、Model Context Protocol仕様に準拠しています。

📦 インストール

前提条件

ソフトウェア

• Python 3.8以上
• uv (推奨パッケージマネージャー)
• Git (リポジトリのクローン用)

インフラストラクチャとアクセス

• Amazon Redshiftクラスターへのアクセス
• Redshift Data API (redshift-data:*) を使用し、指定されたSecrets Managerシークレットにアクセスする (secretsmanager:GetSecretValue) 権限を持つAWSアカウント
• AWS Secrets Managerに資格情報が保存されているRedshiftユーザーアカウント。このユーザーは、このサーバーが有効にするアクションを実行するために必要な権限をRedshift内に持っている必要があります（例: データベースへの CONNECT、対象テーブルの SELECT、関連するシステムビューの SELECT など）。最小特権の原則に基づくロールの使用を強くお勧めします。セキュリティに関する考慮事項 を参照してください。

資格情報

Redshift接続詳細はAWS Secrets Managerを介して管理され、サーバーはRedshift Data APIを使用して接続します。以下が必要です。

• Redshiftクラスター識別子
• クラスター内のデータベース名
• データベース資格情報（ユーザー名とパスワード）を含むAWS Secrets ManagerシークレットのARN
• クラスターとシークレットが存在するAWSリージョン
• オプションで、デフォルトの資格情報/リージョンを使用しない場合はAWSプロファイル名

これらの詳細は、設定 セクションで詳述されているように、環境変数を介して設定されます。

設定

環境変数を設定する必要があります。このサーバーは、AWS Data APIを介してRedshiftクラスターに接続するために、以下の環境変数を必要とします。これらは、シェルで直接設定するか、systemdサービスファイル、Docker環境ファイルを使用するか、プロジェクトのルートディレクトリに .env ファイルを作成して設定できます（uv や python-dotenv などの .env からの読み込みをサポートするツールを使用する場合）。

シェルエクスポートを使用した例

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" # オプション

.env ファイルの例（.env.example を参照）

# Redshift MCP Server設定用の.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" # Or AWS_DEFAULT_REGION
# AWS_PROFILE="your-aws-profile-name" # オプション

必要な変数の表

注: Boto3が使用するAWS資格情報（環境、プロファイル、またはIAMロールを介して）が、指定された REDSHIFT_SECRET_ARN にアクセスし、Redshift Data 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ツール

TO DO

• [ ] プロンプトオプションを改善する
• [ ] より多くの資格情報方法をサポートする
• [ ] 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) ファイルを参照してください。

参考文献

• このプロジェクトは、Model Context Protocol仕様 に大きく依存しています。
• Model Context Protocol が提供する公式のMCP SDKを使用して構築されています。
• AWS SDK for Python (Boto3) を利用して、Amazon Redshift Data API とやり取りしています。
• 多くの診断SQLスクリプトは、優れた awslabs/amazon-redshift-utils リポジトリから適応されています。