Spark SQL

Spark SQL MCP 服务

一个 MCP 服务，可通过 Thrift/HiveServer2 协议让 AI 助手查询 Spark SQL 集群。

兼容任何 HiveServer2 系统：Apache Spark、AWS EMR、Hive、Impala、Presto。

功能

• 查询 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

快速开始

1. 设置环境变量

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

2. 添加到 Claude Code

全局（所有项目）——在项目的 mcpServers 下添加到 ~/.claude.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"
      }
    }
  }
}

项目级别——在仓库中的 .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 Desktop

添加到 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 位客户”

可用工具

工具	说明
list_databases	列出所有可用数据库
list_tables	列出数据库中的表
describe_table	获取表架构（列、类型）
execute_query	运行只读 SQL 查询并返回格式化结果

身份验证

无身份验证（默认）

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"  # default
# Ensure you have a valid Kerberos ticket (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 Server，并附带示例数据，用于集成测试。

# Start the Spark Thrift Server
cd docker && docker compose up -d

# Wait for it to be ready (takes ~30s on first start)
docker logs -f spark-thrift-server  # look for "Sample data loaded."

# Run integration tests
pytest -m integration -v

# Tear down
cd docker && docker compose down -v

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

默认情况下，pytest 会运行单元测试（除非指定 -m integration，否则会跳过集成测试）。

在 Claude Code 中使用本地服务

Docker Spark 服务运行后，将其添加到 MCP 配置中，即可交互式测试该服务。

全局——在项目的 mcpServers 下添加到 ~/.claude.json：

{
  "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 Code 会话，并让它查询示例数据。

安全

只读限制

execute_query 工具仅允许执行只读 SQL 语句。查询必须以以下关键字之一开头：SELECT、SHOW、DESCRIBE、DESC、EXPLAIN 或 WITH。所有其他语句类型（DROP、INSERT、DELETE、CREATE、ALTER、SET、ADD JAR 等）都会在到达 Spark 集群前被拒绝。

错误信息清理

数据库错误会在返回给 MCP 客户端之前进行清理。不会暴露服务器主机名、文件路径和堆栈跟踪等内部细节。连接失败时只报告目标主机/端口和错误类型。

凭据处理

• 密码不会包含在日志输出或错误消息中
• SparkConfig 对象在字符串表示中会隐藏密码
• 在 MCP 注册表架构中，SPARK_PASSWORD 被标记为密钥

已知限制

• 不支持 TLS/SSL — Thrift 连接未加密。在生产环境中使用 LDAP 身份验证时，请通过 SSH 隧道保护传输中的凭据。
• 无查询超时 — 长时间运行的查询不会自动取消。请依赖 Spark 集群级别的超时配置。
• 无按用户访问控制 — 所有查询都以配置的 Spark 用户权限执行。请使用 HiveServer2 授权（Ranger、Sentry）在数据库级别限制访问。
• 身份验证模式默认为 NONE — 适用于本地开发，但不适用于生产环境。在需要身份验证的环境中，将 SPARK_AUTH 设置为 LDAP 或 KERBEROS。

许可证

MIT