Spark SQL

Spark SQL MCP Server

AI アシスタントが Thrift/HiveServer2 プロトコル経由で Spark SQL クラスターにクエリを実行できるようにするMCPサーバーです。

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 オブジェクトは、文字列表現でパスワードをマスクします
• SPARK_PASSWORD は、MCP レジストリスキーマでシークレットとして指定されています

既知の制限事項

• TLS/SSL はサポートされていません — Thrift 接続は暗号化されません。LDAP 認証を使用して本番環境で利用する場合は、SSH トンネルを使用して転送中の認証情報を保護してください。
• クエリタイムアウトはありません — 長時間実行されるクエリは自動的にキャンセルされません。Spark クラスターレベルのタイムアウト設定を利用してください。
• ユーザーごとのアクセス制御はありません — すべてのクエリは、設定された Spark ユーザーの権限で実行されます。データベースレベルでアクセスを制限するには、HiveServer2 の認可機能（Ranger、Sentry）を使用してください。
• 認証モードのデフォルトは NONE です — ローカル開発には適していますが、本番環境には適していません。認証が必要な環境では、SPARK_AUTH を LDAP または KERBEROS に設定してください。

ライセンス

MIT