Spark SQL MCP Server

Spark SQL MCP服务器

一 主控程序 该服务器使AI助手能够通过Thrift/HiveServer2协议查询Spark SQL集群。

适用于任何兼容HiveServer2的系统： Apache Spark, AWS-EMR, 蜂巢, 黑斑羚, Presto.

特性

• 查询Spark SQL --对Spark集群执行只读SQL查询
• 架构发现 --列出数据库、表并描述表结构
• 多种身份验证方法 --无、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.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 在您的repo中：

{
  "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_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.查询

问克劳德这样的问题：

• “我们的Spark集群中有哪些可用的数据库？”
• “向我展示 sales.transactions 桌子”
• “从分析数据库中按收入查询前10名客户”

可用工具

认证

无身份验证（默认）

export SPARK_AUTH="NONE"

轻量级目录访问协议

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

刻耳柏洛斯

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

1. 集 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配置中，以交互方式测试服务器。

全球 --添加到 ~/.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 Code会话，并要求它查询示例数据。

安全

只读执行

这 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 --节俭连接是未加密的。对于LDAP身份验证的生产使用，请使用SSH隧道来保护传输中的凭据。
• 无查询超时 --长时间运行的查询不会自动取消。依赖Spark集群级超时配置。
• 无用户访问控制 --所有查询都以配置的Spark用户的权限执行。使用HiveServer2授权（Ranger、Sentry）在数据库级别限制访问。
• 身份验证模式默认为NONE --适合当地发展，但不适合生产。集 SPARK_AUTH 到 LDAP 或 KERBEROS 对于经过身份验证的环境。

许可证

麻省理工学院