Spark Sql MCP Server

🚀 Spark SQL MCP Server

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

このサーバーは、Apache Spark、AWS EMR、Hive、Impala、Prestoなど、HiveServer2互換のシステムすべてで動作します。

✨ 主な機能

• 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"        # デフォルト
export SPARK_DATABASE="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人の顧客をクエリしてください"

📚 ドキュメント

🔧 技術詳細

認証

認証なし（デフォルト）

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 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