PySpark MCP Server

SQL migration assistance, AWS Glue job generation, and Spark code optimization — as an MCP server.

What It Does

• SQL Dialect Transpilation — Convert between PostgreSQL, Oracle, Redshift, MySQL, Snowflake, and Spark SQL using SQLGlot

• PySpark DataFrame API Generation — Generate DataFrame API code from SQL with optimization hints

• AWS Glue Integration — Job templates, DynamicFrame conversions, Data Catalog definitions, S3 optimization strategies

• Batch Processing — Process hundreds of SQL files concurrently

• Code Review & Optimization — Analyze existing PySpark code for performance improvements

• Pattern Detection — Find code duplication and suggest refactoring

Related MCP server: Claude MCP Data Engineer Server

What It Doesn't Do

• Recursive CTEs → provides Spark SQL equivalent + guidance (PySpark has no native recursive CTE support)

• MERGE/PIVOT/CONNECT BY → transpiles to Spark SQL, provides DataFrame API guidance

• Perfect 1:1 DataFrame API transpilation for all SQL — complex queries get Spark SQL + optimization recommendations

Quick Start

pip install -e .
pyspark-mcp  # starts the MCP server

MCP Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pyspark": {
      "command": "pyspark-mcp",
      "args": []
    }
  }
}

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp:
  servers:
    pyspark:
      command: pyspark-mcp
      enabled_tools: all

Docker

docker compose up -d

Tools

SQL Conversion

• convert_sql_to_pyspark — Convert SQL to PySpark with dialect detection

• analyze_sql_context — Analyze SQL complexity and suggest approach

AWS Glue

• generate_aws_glue_job_template — Generate complete Glue job scripts

• convert_dataframe_to_dynamic_frame — DataFrame ↔ DynamicFrame conversion

• generate_data_catalog_table_definition — Data Catalog table definitions

• generate_incremental_processing_job — Incremental/CDC job generation

• analyze_s3_optimization_opportunities — S3 layout and partitioning analysis

Optimization

• review_pyspark_code — Code review with performance recommendations

• optimize_pyspark_code — Suggest optimizations for existing code

• recommend_join_strategy — Broadcast vs shuffle join recommendations

• suggest_partitioning_strategy — Partitioning recommendations

Batch Processing

• batch_process_files — Process multiple SQL files concurrently

• batch_process_directory — Convert entire directories

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Test
pytest tests/ -v --cov=pyspark_tools

# Format
black pyspark_tools tests
isort pyspark_tools tests

# Lint
flake8 pyspark_tools tests

Architecture

pyspark_tools/
├── server.py              # FastMCP server + tool definitions
├── sql_converter.py       # SQLGlot-based transpilation + DataFrame API generation
├── aws_glue_integration.py # Glue job templates, DynamicFrame, Data Catalog
├── advanced_optimizer.py  # Performance analysis + optimization suggestions
├── batch_processor.py     # Concurrent file processing
├── code_reviewer.py       # PySpark code review patterns
├── duplicate_detector.py  # Code deduplication
├── data_source_analyzer.py # Data source analysis
└── file_utils.py          # File I/O utilities

CI/CD

• ✅ 256 tests passing

• ✅ 71% code coverage

• ✅ Code quality checks (black, isort, flake8)

• ✅ Python 3.11 tested

License

MIT — see LICENSE.

mcp-name: io.github.AnnasMazhar/pyspark-mcp