Spark Sql MCP Server

🚀 Spark SQL MCP 服務器

這是一個 MCP 服務器，它允許 AI 助手通過 Thrift/HiveServer2 協議查詢 Spark SQL 集群。

該服務器可與任何兼容 HiveServer2 的系統配合使用，包括 Apache Spark、AWS EMR、Hive、Impala 和 Presto。

🚀 快速開始

1. 設置環境變量

export SPARK_HOST="your-emr-master-node.amazonaws.com"
export SPARK_PORT="10000"        # 默認值
export SPARK_DATABASE="default"  # 默認值
export SPARK_AUTH="NONE"         # 可選值：NONE | LDAP | KERBEROS | CUSTOM | NOSASL

2. 添加到 Claude 代碼配置

全局配置（適用於所有項目）：將以下內容添加到 ~/.claude.json 文件中項目的 mcpServers 部分。

{
  "mcpServers": {
    "spark-sql": {
      "command": "uvx",
      "args": ["spark-sql-mcp-server"],
      "env": {
        "SPARK_HOST": "your-emr-master-node.amazonaws.com",
        "SPARK_PORT": "10000",
        "SPARK_AUTH": "NONE"
      }
    }
  }
}

項目級配置：將以下內容添加到倉庫的 .claude/mcp.json 文件中。

{
  "mcpServers": {
    "spark-sql": {
      "command": "uvx",
      "args": ["spark-sql-mcp-server"],
      "env": {
        "SPARK_HOST": "your-emr-master-node.amazonaws.com",
        "SPARK_PORT": "10000",
        "SPARK_AUTH": "NONE"
      }
    }
  }
}

3. 添加到 Claude 桌面配置

將以下內容添加到 claude_desktop_config.json 文件中。

{
  "mcpServers": {
    "spark-sql": {
      "command": "uvx",
      "args": ["spark-sql-mcp-server"],
      "env": {
        "SPARK_HOST": "your-emr-master-node.amazonaws.com",
        "SPARK_PORT": "10000"
      }
    }
  }
}

4. 進行查詢

向 Claude 提出類似以下的問題：

• "我們的 Spark 集群中有哪些可用的數據庫？"
• "顯示 sales.transactions 表的架構"
• "從 analytics 數據庫中查詢收入最高的前 10 個客戶"

✨ 主要特性

• 查詢 Spark SQL：對 Spark 集群執行只讀 SQL 查詢。
• 模式發現：列出數據庫、表，並描述表結構。
• 多種認證方法：支持 NONE、LDAP、NOSASL、CUSTOM 和 Kerberos 認證。
• 與 EMR 兼容：可直接與 AWS EMR 集群配合使用。
• 只讀限制：僅允許執行 SELECT、SHOW、DESCRIBE、EXPLAIN 和 WITH 語句。
• 安全默認設置：對無界查詢自動添加 LIMIT 子句，對錯誤消息進行清理。

📦 安裝指南

pip install spark-sql-mcp-server

或者使用 uvx 直接運行：

uvx spark-sql-mcp-server

💻 使用示例

基礎用法

在配置好環境變量和 Claude 配置後，就可以向 Claude 提出 SQL 查詢相關的問題，例如：

# 詢問可用數據庫
"What databases are available in our Spark cluster?"

高級用法

可以根據不同的認證方式和具體需求，靈活配置環境變量和 Claude 配置，以滿足不同場景的查詢需求。例如，使用 LDAP 認證時：

export SPARK_AUTH="LDAP"
export SPARK_USERNAME="your-username"
export SPARK_PASSWORD="your-password"

📚 詳細文檔

可用工具

認證方式

無認證（默認）

export SPARK_AUTH="NONE"

LDAP 認證

export SPARK_AUTH="LDAP"
export SPARK_USERNAME="your-username"
export SPARK_PASSWORD="your-password"

Kerberos 認證

export SPARK_AUTH="KERBEROS"
export SPARK_KERBEROS_SERVICE_NAME="hive"  # 默認值
# 確保你有有效的 Kerberos 票據（kinit）

AWS EMR 設置

1. 安全組：允許從你的 IP 地址訪問端口 10000 的入站流量。
2. SSH 隧道（推薦）：

ssh -i your-key.pem -L 10000:localhost:10000 hadoop@your-emr-master

3. 設置 SPARK_HOST=localhost

開發

git clone https://github.com/aidancorrell/spark-sql-mcp-server.git
cd spark-sql-mcp-server
pip install -e ".[dev]"
pytest
ruff check .

使用 Docker 進行本地測試

Docker Compose 配置提供了一個帶有示例數據的本地 Spark Thrift 服務器，用於集成測試。

# 啟動 Spark Thrift 服務器
cd docker && docker compose up -d

# 等待服務器準備好（首次啟動約需 30 秒）
docker logs -f spark-thrift-server  # 查找 "Sample data loaded."

# 運行集成測試
pytest -m integration -v

# 關閉服務器
cd docker && docker compose down -v

本地服務器包含示例表：default.employees、default.orders 和 test_db.metrics。

默認情況下，pytest 會運行單元測試（除非指定 -m integration，否則會跳過集成測試）。

在 Claude 代碼中使用本地服務器

在 Docker Spark 服務器運行時，將其添加到 MCP 配置中，以交互式測試服務器。

全局配置：將以下內容添加到 ~/.claude.json 文件中項目的 mcpServers 部分。

{
  "spark-sql": {
    "command": "uvx",
    "args": ["spark-sql-mcp-server"],
    "env": {
      "SPARK_HOST": "localhost",
      "SPARK_PORT": "10000",
      "SPARK_AUTH": "NONE"
    }
  }
}

項目級配置：將以下內容添加到 .claude/mcp.json 文件中。

{
  "mcpServers": {
    "spark-sql": {
      "command": "uvx",
      "args": ["spark-sql-mcp-server"],
      "env": {
        "SPARK_HOST": "localhost",
        "SPARK_PORT": "10000",
        "SPARK_AUTH": "NONE"
      }
    }
  }
}

然後啟動一個新的 Claude 代碼會話，並讓它查詢示例數據。

🔧 技術細節

只讀限制

execute_query 工具僅允許執行只讀 SQL 語句。查詢必須以 SELECT、SHOW、DESCRIBE、DESC、EXPLAIN 或 WITH 開頭。所有其他類型的語句（如 DROP、INSERT、DELETE、CREATE、ALTER、SET、ADD JAR 等）在到達 Spark 集群之前會被拒絕。

錯誤清理

數據庫錯誤在返回給 MCP 客戶端之前會進行清理。不會暴露服務器主機名、文件路徑和堆棧跟蹤等內部細節。連接失敗僅報告目標主機/端口和錯誤類型。

憑證處理

• 密碼不會包含在日誌輸出或錯誤消息中。
• SparkConfig 對象在其字符串表示中會屏蔽密碼。
• SPARK_PASSWORD 在 MCP 註冊表模式中被標記為機密信息。

已知限制

• 不支持 TLS/SSL：Thrift 連接未加密。在使用 LDAP 認證的生產環境中，建議使用 SSH 隧道來保護傳輸中的憑證。
• 無查詢超時：長時間運行的查詢不會自動取消。依賴於 Spark 集群級別的超時配置。
• 無用戶級訪問控制：所有查詢都以配置的 Spark 用戶的權限執行。建議使用 HiveServer2 授權（Ranger、Sentry）在數據庫級別限制訪問。
• 認證模式默認為 NONE：適用於本地開發，但不適用於生產環境。在需要認證的環境中，將 SPARK_AUTH 設置為 LDAP 或 KERBEROS。

📄 許可證

本項目採用 MIT 許可證。