Redshift MCP Server

该 MCP（Model Context Protocol）服务器为 Claude Desktop 及其他兼容 MCP 的客户端提供对 Amazon Redshift 数据库的安全、只读访问。它充当智能桥梁，使 AI 助手能够独立导航、理解并直接从您的数据仓库中提取洞察。

✨ 核心特性

• 10 个专用工具：一整套用于数据发现、元数据提取、查询和导出的工具。

• 动态配置：可通过 .env 完全配置（白名单、行数限制、连接参数）。

• 传输模式：支持 stdio（适用于 Claude Desktop 等本地客户端）和 sse（通过 HTTP 进行远程连接的 Server-Sent Events）。

• 连接缓存：高效的连接管理，与 Redshift 保持单一长期存活的健康检查连接。

• 企业级安全：

  • 严格只读 SQL 校验。

  • Schema 白名单（将 AI 限制在预先批准的 schema 内）。

  • 对查询和导出的行数设置硬性上限，以保护数据库性能。

• SSH 隧道支持：通过内置的 sshtunnel 无缝连接私有 VPC 中的 Redshift 集群。

Related MCP server: safedb-mcp

🛠️ 可用的 MCP 工具

数据发现与导航

1. get_allowed_schemas：返回服务器的 schema 访问配置（白名单、默认 schema、限制）。

2. list_schemas：发现数据库中可访问的 schema（按配置的白名单过滤）。

3. list_tables：列出某个 schema 中的所有表。只有白名单中的 schema 可被访问。

4. describe_table：获取表的列名、数据类型、可空性和默认值。

5. search_columns：在允许的 schema 的所有表中，搜索名称与关键字匹配（不区分大小写）的列。

数据分析与提取

6. sample_data：返回表中的少量样本行，用于数据探索。

7. table_row_count：使用 COUNT(*) 获取表的精确行数。

8. query_data：执行只读 SELECT 查询。根据服务器配置自动包装并限制结果。

9. explain_query：在执行前显示查询的 EXPLAIN 计划，以了解性能。

10. export_to_csv：将查询结果导出为 CSV 格式，并具有更高的专用行数限制（MAX_EXPORT_ROWS）。

🚀 设置与安装

1. 安装依赖

# Clone the repository
git clone <repository-url>
cd redshift-mcp-server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. 配置环境

复制示例环境文件并使用您的凭据进行编辑：

cp .env.example .env

编辑 .env 文件以配置您的 Redshift 连接和服务器限制：

# --- Redshift Connection ---
RS_HOST=your-cluster.region.redshift.amazonaws.com
RS_DB=your_database_name
RS_USER=your_readonly_user
RS_PASS=your_password
RS_PORT=5439

# --- Security & Limits ---
ALLOWED_SCHEMAS=gold_capsaai,report_capsaai
DEFAULT_SCHEMA=gold_capsaai
MAX_ROWS=500
MAX_EXPORT_ROWS=5000

# --- SSH Tunnel (For Private VPCs) ---
SSH_TUNNEL=false
# If true, provide SSH_HOST, SSH_USER, SSH_KEY_FILE, etc.

3. 启动服务器

模式 1：stdio（默认） 当 MCP 客户端（例如 Claude Desktop）运行在同一台机器上时最佳。

python server.py

模式 2：sse（HTTP） 最适合通过 HTTP 或隧道远程访问服务器。

# Start SSE on port 8000
python server.py --sse --host 0.0.0.0 --port 8000

🔌 连接服务器

选项 A：本地 Claude Desktop（stdio）

如果您的 Claude Desktop 与服务器运行在同一台机器上，请编辑您的 Claude Desktop 配置文件：

• Mac：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "redshift": {
      "command": "/absolute/path/to/redshift-mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/redshift-mcp-server/server.py"]
    }
  }
}

选项 B：远程连接（SSE + IDE）

如果服务器运行在远程 EC2 实例上，请以 --sse 模式启动服务器。

对于支持直接 SSE 连接的 IDE（如带有 Cline 的 VS Code）：

1. 添加一个新的 MCP 服务器。

2. 将传输类型设置为 SSE。

3. 使用 URL：http://<EC2-IP>:8000/sse（或您的隧道 URL）。

🧪 测试与验证

该仓库包含一套全面的测试套件和诊断工具：

• client.py：一个 CLI 客户端，对所有 10 个工具运行端到端冒烟测试。

• test_connection.py：基本连接验证。

• test_restricted_access.py：确保 schema 安全限制正常工作。

• monitor_mcp.sh：生产级监控，支持自动重启、健康检查和日志记录。

🏗️ 架构

graph TB
    subgraph "Client Layer"
        CD["Claude Desktop / MCP Client"]
    end
    
    subgraph "MCP Server Layer"
        MCP["FastMCP Server"]
        CONFIG["config.py / .env"]
        VALIDATION["SQL & Schema Validation"]
    end
    
    subgraph "Network Layer"  
        SSH["SSH Tunnel<br/>(Optional)"]
        CONN["Connection Cache"]
    end
    
    subgraph "Database Layer"
        RS["Amazon Redshift"]
        SCHEMA["Allowed Schemas"]
    end
    
    CD -->|"JSON-RPC (stdio/sse)"| MCP
    MCP --> CONFIG
    MCP --> VALIDATION
    VALIDATION --> CONN
    CONN --> SSH
    SSH --> RS
    RS --> SCHEMA

🔐 安全注意事项

• 只读：_validate_read_only_sql 包装器严格将查询限制为 SELECT 和 EXPLAIN 语句。

• 限制引擎：通过 _apply_limit 中的正则表达式解析防止双重 LIMIT 语法错误，确保大表扫描被限制在您的 .env 阈值之内。

• Schema 隔离：AI 无法查看或查询 ALLOWED_SCHEMAS 逗号分隔列表之外的任何表。

• 保护凭据安全：切勿将您的 .env 或 .json 配置文件提交到版本控制。默认情况下，它们已被 .gitignore 忽略。