redshift-utils-mcp
Redshift Utils MCP サーバー
概要
このプロジェクトは、Amazon Redshift データベースと対話するために特別に設計された Model Context Protocol (MCP) サーバーを実装します。
これは、大規模言語モデル(LLM)やAIアシスタント(Claude、Cursor、カスタムアプリケーションなど)とRedshiftデータウェアハウス間のギャップを埋め、安全で標準化されたデータアクセスとインタラクションを実現します。これにより、ユーザーは自然言語またはAI駆動型のプロンプトを使用して、データのクエリ、データベース構造の理解、監視/診断操作を行うことができます。
このサーバーは、LLM 機能を構造化された安全な方法で Amazon Redshift データ環境に直接統合することを検討している開発者、データアナリスト、またはチーム向けです。
Related MCP server: Redshift MCP Server
目次
特徴
✨セキュアな 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 クラスターの識別子。 |
|
| はい | 接続するデータベースの名前。 |
|
| はい | Redshift 認証情報の AWS Secrets Manager ARN。 |
|
| はい | Data API および Secrets Manager の AWS リージョン。 |
|
| いいえ | AWS リージョンを指定するための |
|
| いいえ | 認証情報ファイル (~/.aws/...) から使用する AWS プロファイル名。 |
|
注意: 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の例 |
| サーバーの |
|
| 接続されたデータベース内のアクセス可能なすべてのユーザー定義スキーマを一覧表示します。 |
|
| 現在のワークロード管理 (WLM) 構成の詳細を取得します。 |
|
| 指定された |
|
リクエストを行う際は、 {script_path}と{schema_name}を実際の値に置き換えてください。スキーマ/テーブルへのアクセスは、 REDSHIFT_SECRET_ARNで設定されたRedshiftユーザーの権限に依存します。
利用可能なMCPツール
ツール名 | 説明 | 主要なパラメータ(必須*) | 呼び出し例 |
| 一連の診断 SQL スクリプトを使用して、Redshift クラスターのヘルス評価を実行します。 |
|
|
| クラスター内のアクティブなロック競合とブロックしているセッションを識別します。 |
|
|
| プラン、メトリック、履歴データなど、特定のクエリの実行パフォーマンスを分析します。 |
|
|
| Redshift Data API 経由でユーザーが提供した任意の SQL クエリを実行します。エスケープハッチとして設計されています。 |
|
|
| 特定のテーブルの DDL (データ定義言語) ステートメント ( |
|
|
| 特定の Redshift テーブルに関する、設計、ストレージ、健全性、使用状況などの詳細情報を取得します。 |
|
|
| さまざまな診断スクリプトを使用して、指定された時間枠内のクラスターのワークロード パターンを分析します。 |
|
|
やること
[ ] プロンプトオプションの改善
[ ] より多くの認証方法のサポートを追加
[ ] 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リポジトリから採用されています。
Available Tools
7 toolshandle_check_cluster_healthA
Performs a health assessment of the Redshift cluster.
Executes a series of diagnostic SQL scripts concurrently based on the
specified level ('basic' or 'full'). Aggregates raw results or errors
from each script into a dictionary.
Args:
ctx: The MCP context object.
level: Level of detail: 'basic' for operational status, 'full' for
comprehensive table design/maintenance checks. Defaults to 'basic'.
time_window_days: Lookback period in days for time-sensitive checks
(e.g., queue waits, commit waits). Defaults to 1.
Returns:
A dictionary where keys are script names and values are either the raw
list of dictionary results from the SQL query or an Exception object
if that specific script failed.
Raises:
DataApiError: If a critical error occurs during script execution that
prevents gathering results (e.g., config error). Individual
script errors are captured within the returned dictionary.
Inputs: level, time_window_days.
handle_diagnose_locksA
Identifies active lock contention in the cluster.
Fetches all current lock information and then filters it based on the
optional target PID, target table name, and minimum wait time.
Formats the results into a list of contention details and a summary.
Args:
ctx: The MCP context object.
target_pid: Optional: Filter results to show locks held by or waited
for by this specific process ID (PID).
target_table_name: Optional: Filter results for locks specifically on
this table name (schema qualification recommended
if ambiguous).
min_wait_seconds: Minimum seconds a lock must be in a waiting state
to be included. Defaults to 5.
Returns:
A list of dictionaries, where each dictionary represents a row
from the lock contention query result.
Raises:
DataApiError: If fetching the initial lock information fails.
Inputs: min_wait_seconds, target_pid, target_table_name.
handle_diagnose_query_performanceA
Analyzes a specific query's execution performance.
Fetches query text, execution plan, metrics, alerts, compilation info,
skew details, and optionally historical run data. Uses a formatting
utility to synthesize this into a structured report with potential issues
and recommendations.
Args:
ctx: The MCP context object.
query_id: The numeric ID of the Redshift query to analyze.
compare_historical: Fetch performance data for previous runs of the
same query text. Defaults to True.
Returns:
A dictionary conforming to DiagnoseQueryPerformanceResult structure:
- On success: Contains detailed performance breakdown, issues, recommendations.
- On query not found: Raises QueryNotFound exception.
- On other errors: Raises DataApiError or similar for FastMCP to handle.
Raises:
DataApiError: If a critical error occurs during script execution or parsing.
QueryNotFound: If the specified query_id cannot be found in key tables.
Inputs: query_id (required), compare_historical.
handle_execute_ad_hoc_queryA
Executes an arbitrary SQL query provided by the user via Redshift Data API.
Designed as an escape hatch for advanced users or queries not covered by
specialized tools. Returns a structured dictionary indicating success
(with results) or failure (with error details).
Args:
ctx: The MCP context object.
sql_query: The exact SQL query string to execute.
Returns:
A dictionary conforming to ExecuteAdHocQueryResult structure:
- On success: {"status": "success", "columns": [...], "rows": [...], "row_count": ...}
- On error: {"status": "error", "error_message": "...", "error_type": "..."}
(Note: Actual return might be handled by FastMCP error handling for raised exceptions)
Raises:
DataApiConfigError: If configuration is invalid.
SqlExecutionError: If the SQL execution itself fails.
DataApiTimeoutError: If the Data API call times out.
DataApiError: For other Data API related errors or unexpected issues.
ClientError: For AWS client-side errors.
Inputs: sql_query (required).
handle_get_table_definitionA
Retrieves the DDL (Data Definition Language) statement for a specific table.
Executes a SQL script designed to generate or retrieve the CREATE TABLE
statement for the given table.
Args:
ctx: The MCP context object.
schema_name: The schema name of the table.
table_name: The name of the table.
Returns:
A dictionary conforming to GetTableDefinitionResult structure:
- On success: {"status": "success", "ddl": "<CREATE TABLE statement>"}
- On table not found or DDL retrieval error:
{"status": "error", "error_message": "...", "error_type": "..."}
Raises:
TableNotFound: If the specified table is not found.
DataApiError: If a critical, unexpected error occurs during execution.
Inputs: schema_name (required), table_name (required).
handle_inspect_tableA
Retrieves detailed information about a specific Redshift table.
Fetches table OID, then concurrently executes various inspection scripts
covering design, storage, health, usage, and encoding.
Args:
ctx: The MCP context object.
schema_name: The schema name of the table.
table_name: The name of the table.
Returns:
A dictionary where keys are script names and values are either the raw
list of dictionary results from the SQL query, the extracted DDL string,
or an Exception object if that specific script failed.
- On success: Dictionary containing raw results or Exception objects for each script.
- On table not found: Raises TableNotFound exception.
- On critical errors (e.g., OID lookup failure): Raises DataApiError or similar.
Raises:
DataApiError: If a critical error occurs during script execution.
TableNotFound: If the specified table cannot be found via its OID.
Inputs: schema_name (required), table_name (required).
handle_monitor_workloadA
Analyzes cluster workload patterns over a specified time window.
Executes various SQL scripts concurrently to gather data on resource usage,
WLM performance, top queries, queuing, COPY performance, and disk-based
queries. Returns a dictionary containing the raw results (or Exceptions)
keyed by the script name.
Args:
ctx: The MCP context object.
time_window_days: Lookback period in days for the workload analysis.
Defaults to 2.
top_n_queries: Number of top queries (by total execution time) to
consider for the 'top_queries.sql' script. Defaults to 10.
Returns:
A dictionary where keys are script names (e.g., 'workload/top_queries.sql')
and values are either a list of result rows (as dictionaries) or the
Exception object if that script failed.
Raises:
DataApiError: If a critical error occurs during configuration loading.
(Note: Individual script errors are returned in the result dict).
Inputs: time_window_days, top_n_queries.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct purpose with clear boundaries: cluster health assessment, lock diagnosis, query performance analysis, ad-hoc query execution, table definition retrieval, table inspection, and workload monitoring. There is no functional overlap between tools, and the descriptions clearly differentiate their specific use cases.
All tools follow a 'handle_verb_noun' prefix pattern, which provides some consistency. However, the verb choices are mixed ('check', 'diagnose', 'execute', 'get', 'inspect', 'monitor'), making the naming somewhat inconsistent in terms of action semantics. The structure is predictable but the verb selection lacks uniformity.
With 7 tools, this server is well-scoped for Redshift cluster diagnostics and management. Each tool serves a specific, valuable function in the domain, and there are no redundant or trivial tools. The count is appropriate for covering key operational and troubleshooting tasks without being overwhelming.
The toolset covers essential diagnostic and operational areas for Redshift: health checks, lock analysis, query performance, ad-hoc queries, table definitions, table inspection, and workload monitoring. Minor gaps exist, such as lack of tools for cluster configuration changes, user/role management, or backup operations, but core diagnostic workflows are well-covered.
Maintenance
Related MCP Connectors
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Related MCP Servers
- AlicenseBqualityBmaintenanceModel Context Protocol (MCP) server that integrates Redash with AI assistants like Claude, allowing them to query data, manage visualizations, and interact with dashboards through natural language.674,563 npm108MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI assistants to interact with Amazon Redshift databases, allowing for schema exploration, query execution, and statistics collection.32Apache 2.0
- AlicenseAqualityBmaintenanceA Snowflake MCP server — SQL queries, schema exploration, and data insights for AI assistants6307 PyPI2MIT
- AlicenseAqualityDmaintenanceModel Context Protocol (MCP) server for Redash - manage queries, dashboards, and visualizations through AI assistants like Claude.6202 PyPIMIT