Redshift Utils MCP Server

Redshift Utils MCP サーバー

概要

このプロジェクトは、Amazon Redshift データベースとの連携に特化して設計された Model Context Protocol（MCP）サーバーを実装します。

Large Language Models（LLM）や AI アシスタント（Claude、Cursor、カスタムアプリケーションなどに搭載されているもの）と、Redshift データウェアハウスとの橋渡しを行い、安全で標準化されたデータアクセスと連携を可能にします。これにより、ユーザーは自然言語や AI 主導のプロンプトを使って、データのクエリ、データベース構造の把握、監視や診断を行うことができます。

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

目次

• 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）を提供します。
• 📝 読み取り専用クエリの実行： 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）を提供します。
• 🛡️ 入力のサニタイズ： SQL インジェクションのリスクを軽減するため、適用可能な場合は Boto3 Redshift Data API クライアントを介してパラメーター化クエリを使用します。
• 🧩 標準化された MCP インターフェース： 互換性のあるクライアント（Claude Desktop、Cursor IDE、カスタムアプリケーションなど）とシームレスに統合できるよう、Model Context Protocol 仕様に準拠しています。

前提条件

ソフトウェア：

• Python 3.10+
• uv（推奨パッケージマネージャー）または pip

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

• Amazon Redshift クラスターへのアクセス。
• Redshift Data API の使用（redshift-data:*）と、指定した Secrets Manager シークレットへのアクセス（secretsmanager:GetSecretValue）に必要な権限を持つ AWS アカウント。
• AWS Secrets Manager に認証情報が保存されている Redshift ユーザーアカウント。このユーザーには、このサーバーで有効になっている操作を実行するための 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 クラスターに接続するために、以下の環境変数を必要とします。これらは、シェルへの直接設定、systemd サービスファイル、Docker 環境ファイル、またはプロジェクトのルートディレクトリに .env ファイルを作成することで設定できます（.env からの読み込みをサポートする uv や python-dotenv などのツールを使用する場合）。

シェルの 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	現在の Workload Management（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 の仕様に大きく依存しています。
• Model Context Protocolが提供する公式 MCP SDK を使用して構築されています。
• Amazon Redshift Data APIとの連携には、Python 用 AWS SDK（Boto3）を使用しています。
• 診断用 SQL スクリプトの多くは、優れたリポジトリである awslabs/amazon-redshift-utils を参考にしています。