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 许可证。