redshift-utils-mcp

Redshift Utils MCP サーバー

概要

このプロジェクトは、Amazon Redshift データベースと対話するために特別に設計された Model Context Protocol (MCP) サーバーを実装します。

これは、大規模言語モデル（LLM）やAIアシスタント（Claude、Cursor、カスタムアプリケーションなど）とRedshiftデータウェアハウス間のギャップを埋め、安全で標準化されたデータアクセスとインタラクションを実現します。これにより、ユーザーは自然言語またはAI駆動型のプロンプトを使用して、データのクエリ、データベース構造の理解、監視/診断操作を行うことができます。

このサーバーは、LLM 機能を構造化された安全な方法で Amazon Redshift データ環境に直接統合することを検討している開発者、データアナリスト、またはチーム向けです。

特徴

✨セキュアな Redshift 接続 (データ API 経由): Boto3 経由で AWS Redshift データ 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 ) を提供します。
📊ワークロード監視: WLM、上位クエリ、リソース使用量など、時間枠全体でクラスターのワークロードパターンを分析するためのツール ( handle_monitor_workload ) が含まれています。
📝 **DDL 取得:**指定されたテーブルのSHOW TABLE出力 (DDL) を取得するためのツール ( handle_get_table_definition ) を提供します。
🛡️**入力サニタイズ:**該当する場合は、Boto3 Redshift Data API クライアントを介してパラメーター化されたクエリを利用し、SQL インジェクションのリスクを軽減します。
🧩**標準化された MCP インターフェース:**互換性のあるクライアント (Claude Desktop、Cursor IDE、カスタムアプリケーションなど) とのシームレスな統合のために、モデルコンテキストプロトコル仕様に準拠しています。

前提条件

ソフトウェア：

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

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

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

資格：

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" # 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:* ) を使用する権限があることを確認してください。

使用法

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"
      }
  }
}

カーソル IDE との接続:

「使用方法 / クイックスタート」セクションの指示に従って、MCP サーバーをローカルで起動します。
カーソルで、コマンドパレットを開きます (Cmd/Ctrl + Shift + P)。
「MCP サーバーに接続」と入力するか、MCP 設定に移動します。
新しいサーバー接続を追加します。
stdioトランスポートタイプを選択します。
サーバーの起動に必要なコマンドと引数を入力してください（ uvx run redshift_utils_mcp ）。実行するコマンドに必要な環境変数が利用可能であることを確認してください。
カーソルはサーバーと利用可能なツール/リソースを検出する必要があります。

利用可能な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のサポートを追加

貢献

貢献を歓迎します！以下のガイドラインに従ってください。

問題の検索/報告: 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が提供する公式 MCP SDK を使用して構築されています。
AWS SDK for Python ( Boto3 ) を使用して、 Amazon Redshift Data APIと対話します。
診断 SQL スクリプトの多くは、優れたawslabs/amazon-redshift-utilsリポジトリから採用されています。

redshift-utils-mcp