The Redshift Utils MCP Server facilitates secure interaction between Amazon Redshift databases and AI tools/LLMs using the Model Context Protocol. It enables:
Secure Connections: Uses AWS Redshift Data API and Secrets Manager for secure database access
Schema Discovery: Lists available schemas and tables
Metadata Retrieval: Gathers detailed table metadata, statistics, and maintenance status
Read-Only Queries: Executes SELECT queries for data retrieval
Performance Analysis: Analyzes execution plans and query metrics
Table Inspection: Provides comprehensive details on table design, storage, health, and usage
Cluster Health Checks: Performs basic or full health assessments
Lock Diagnosis: Identifies lock contention and blocking sessions
Workload Monitoring: Analyzes workload patterns and resource usage
DDL Retrieval: Retrieves CREATE TABLE statements
WLM Configuration: Retrieves Workload Management details
Input Sanitization: Uses parameterized queries to prevent SQL injection
Connects to Amazon Redshift databases, enabling schema discovery, metadata inspection, query execution, performance analysis, and cluster monitoring. Provides tools for diagnosing query performance, checking cluster health, inspecting tables, and retrieving table definitions.
Securely retrieves Redshift database credentials from AWS Secrets Manager, allowing secure authentication without hardcoding credentials in the application.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@redshift-utils-mcp show me the top 10 customers by total sales last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This project implements a Model Context Protocol (MCP) server designed specifically to interact with Amazon Redshift databases.
It bridges the gap between Large Language Models (LLMs) or AI assistants (like those in Claude, Cursor, or custom applications) and your Redshift data warehouse, enabling secure, standardized data access and interaction. This allows users to query data, understand database structure, and monitoring/diagnostic operations using natural language or AI-driven prompts.
This server is for developers, data analysts, or teams looking to integrate LLM capabilities directly with their Amazon Redshift data environment in a structured and secure manner.
Related MCP server: Redshift MCP Server
✨ Secure Redshift Connection (via Data API): Connects to your Amazon Redshift cluster using the AWS Redshift Data API via Boto3, leveraging AWS Secrets Manager for credentials managed securely via environment variables.
🔍 Schema Discovery: Exposes MCP resources for listing schemas and tables within a specified schema.
📊 Metadata & Statistics: Provides a tool (handle_inspect_table) to gather detailed table metadata, statistics (like size, row counts, skew, stats staleness), and maintenance status.
📝 Read-Only Query Execution: Offers a secure MCP tool (handle_execute_ad_hoc_query) to execute arbitrary SELECT queries against the Redshift database, enabling data retrieval based on LLM requests.
📈 Query Performance Analysis: Includes a tool (handle_diagnose_query_performance) to retrieve and analyze the execution plan, metrics, and historical data for a specific query ID.
🔍 Table Inspection: Provides a tool (handle_inspect_table) to perform a comprehensive inspection of a table, including design, storage, health, and usage.
🩺 Cluster Health Check: Offers a tool (handle_check_cluster_health) to perform a basic or full health assessment of the cluster using various diagnostic queries.
🔒 Lock Diagnosis: Provides a tool (handle_diagnose_locks) to identify and report on current lock contention and blocking sessions.
📊 Workload Monitoring: Includes a tool (handle_monitor_workload) to analyze cluster workload patterns over a time window, covering WLM, top queries, and resource usage.
📝 DDL Retrieval: Offers a tool (handle_get_table_definition) to retrieve the SHOW TABLE output (DDL) for a specified table.
🛡️ Input Sanitization: Utilizes parameterized queries via the Boto3 Redshift Data API client where applicable to mitigate SQL injection risks.
🧩 Standardized MCP Interface: Adheres to the Model Context Protocol specification for seamless integration with compatible clients (e.g., Claude Desktop, Cursor IDE, custom applications).
Software:
Python 3.10+
uv (recommended package manager) or pip
Infrastructure & Access:
Access to an Amazon Redshift cluster.
An AWS account with permissions to use the Redshift Data API (redshift-data:*) and access the specified Secrets Manager secret (secretsmanager:GetSecretValue).
A Redshift user account whose credentials are stored in AWS Secrets Manager. This user needs the necessary permissions within Redshift to perform the actions enabled by this server (e.g., CONNECT to the database, SELECT on target tables, SELECT on relevant system views like pg_class, pg_namespace, svv_all_schemas, svv_tables, `svv_table_info``). Using a role with the principle of least privilege is strongly recommended. See Security Considerations.
Credentials:
Your Redshift connection details are managed via AWS Secrets Manager, and the server connects using the Redshift Data API. You need:
The Redshift cluster identifier.
The database name within the cluster.
The ARN of the AWS Secrets Manager secret containing the database credentials (username and password).
The AWS region where the cluster and secret reside.
Optionally, an AWS profile name if not using default credentials/region.
These details will be configured via environment variables as detailed in the Configuration section.
The easiest way to install the Redshift Utils MCP Server is directly from PyPI:
# Using pip
pip install redshift-utils-mcp
# Using uv (recommended)
uv pip install redshift-utils-mcpAlternatively, you can install from the source repository:
# 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 .Set Environment Variables:
This server requires the following environment variables to connect to your Redshift cluster via the AWS Data API. You can set these directly in your shell, using a systemd service file, a Docker environment file, or by creating a .env file in the project's root directory (if using a tool like uv or python-dotenv that supports loading from .env).
Example using shell 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" # OptionalExample .env file (see .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" # OptionalRequired Variables Table:
Variable Name | Required | Description | Example Value |
| Yes | Your Redshift cluster identifier. |
|
| Yes | The name of the database to connect to. |
|
| Yes | AWS Secrets Manager ARN for Redshift credentials. |
|
| Yes | AWS region for Data API and Secrets Manager. |
|
| No | Alternative to |
|
| No | AWS profile name to use from your credentials file (~/.aws/...). |
|
Note: Ensure the AWS credentials used by Boto3 (via environment, profile, or IAM role) have permissions to access the specified REDSHIFT_SECRET_ARN and use the Redshift Data API (redshift-data:*).
After installation, you can run the server directly from the command line:
# If installed from PyPI
redshift-utils-mcp
# Or using uvx (no installation required)
uvx redshift-utils-mcpAdd the following configuration block to your mcp.json file:
{
"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"
}
}
}Use the Claude CLI to add the server configuration:
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-mcpStart the MCP server locally using the instructions in the Usage / Quickstart section.
In Cursor, open the Command Palette (Cmd/Ctrl + Shift + P).
Type "Connect to MCP Server" or navigate to the MCP settings.
Add a new server connection.
Choose the stdio transport type.
Enter the command and arguments required to start your server (uvx run redshift_utils_mcp). Ensure any necessary environment variables are available to the command being run.
Cursor should detect the server and its available tools/resources.
Resource URI Pattern | Description | Example URI |
| Retrieves the raw content of a SQL script file from the server's |
|
| Lists all accessible user-defined schemas in the connected database. |
|
| Retrieves the current Workload Management (WLM) configuration details. |
|
| Lists all accessible tables and views within the specified |
|
Replace {script_path} and {schema_name} with the actual values when making requests.
Accessibility of schemas/tables depends on the permissions granted to the Redshift user configured via REDSHIFT_SECRET_ARN.
Tool Name | Description | Key Parameters (Required*) | Example Invocation |
| Performs a health assessment of the Redshift cluster using a set of diagnostic SQL scripts. |
|
|
| Identifies active lock contention and blocking sessions in the cluster. |
|
|
| Analyzes a specific query's execution performance, including plan, metrics, and historical data. |
|
|
| Executes an arbitrary SQL query provided by the user via Redshift Data API. Designed as an escape hatch. |
|
|
| Retrieves the DDL (Data Definition Language) statement ( |
|
|
| Retrieves detailed information about a specific Redshift table, covering design, storage, health, and usage. |
|
|
| Analyzes cluster workload patterns over a specified time window using various diagnostic scripts. |
|
|
Improve Prompt Options
Add support for more credential methods
Add Support for Redshift Serverless
This project relies heavily on the Model Context Protocol specification.
Built using the official MCP SDK provided by Model Context Protocol.
Utilizes the AWS SDK for Python (Boto3) to interact with the Amazon Redshift Data API.
Many of the diagnostic SQL scripts are adapted from the excellent awslabs/amazon-redshift-utils repository.
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.
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.
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.
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).
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).
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).
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
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.
