scylladb-mcp-server

andrew-brown-noosphere/scylladb-mcp-server

3.2

If you are the rightful owner of scylladb-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for ScyllaDB featuring a technical engineering advisor, designed to assist developers in migrating from DynamoDB with a focus on cost, performance, and architectural decisions.

Tools
5
Resources
0
Prompts
0

ScyllaDB MCP Server

A Model Context Protocol (MCP) server for ScyllaDB featuring a technical engineering advisor. Enables live A/B testing between DynamoDB and ScyllaDB with honest analysis about costs, performance, and architectural decisions.

Features

  • šŸŽ­ Technical Engineering Voice - Direct analysis, no marketing fluff
  • ā˜ļø Multi-Cloud Support - ScyllaDB Cloud, AWS DynamoDB, and local Docker
  • šŸ’° Advanced Cost Calculator - Matches official ScyllaDB calculator with workload profiles
  • šŸš€ Live A/B Testing - Real-time performance comparison between platforms
  • šŸ” DynamoDB Code Analysis - Pattern detection and migration assessment
  • šŸ“Š Workload Templates - Discord-scale, AdTech, FinTech, and more
  • šŸ› ļø Migration Complexity Assessment - Honest effort estimates

Supported Connections

1. ScyllaDB Cloud

Connect to managed ScyllaDB instances with full CQL and Alternator (DynamoDB API) support.

2. AWS DynamoDB

Native DynamoDB connections for live A/B testing and cost comparison.

3. Local Docker

Auto-provisions ScyllaDB containers for development and testing.

Demo Applications

The MCP server includes several demo applications for real-world testing:

Performance Benchmarks

  • quick_demo.py - Connection speed comparison (ScyllaDB vs DynamoDB)
  • simple_ab_demo.py - Side-by-side write performance test
  • live_ab_test.py - Comprehensive performance comparison with metrics
  • ycsb_benchmark.py - Industry-standard YCSB workload testing

Cost Analysis Tools

  • test_mcp_server.py - Test the advisor with real workload scenarios
  • Advanced Calculator - Matches ScyllaDB's official pricing calculator
  • Workload Templates - Pre-configured profiles for common applications

DynamoDB Analysis

The server includes AWS's official DynamoDB sample application for analysis:

  • Source: Based on AWS's DynamoDB online shop example
  • Location: test/dynamodb_online_shop_example.py
  • Purpose: Analyze real DynamoDB patterns from AWS's own code
  • Features:
    • Query pattern inspection
    • Access pattern analysis
    • Hot partition detection
    • GSI proliferation identification
    • Migration complexity assessment

Quick Start

Prerequisites

  • Python 3.8+ (3.11 recommended)
  • Docker Desktop (for local testing)
  • Claude Desktop or Claude Code with MCP support
  • AWS credentials (for DynamoDB comparison)

Installation

  1. Clone this repository:
git clone https://github.com/scylladb/scylladb-mcp-server.git
cd scylladb-mcp-server
  1. Run the setup script:
./setup.sh
  1. Configure your environment:
# Copy the example environment file
cp .env.example .env

# Edit .env with your credentials:
# - AWS_ACCESS_KEY_ID
# - AWS_SECRET_ACCESS_KEY
# - SCYLLA_ALTERNATOR_ENDPOINT (for ScyllaDB Cloud)
  1. Restart Claude Desktop or Claude Code

Configuration

Claude Desktop Configuration

The setup script automatically configures Claude Desktop. For manual configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scylladb": {
      "command": "python3",
      "args": ["/path/to/scylladb-mcp-server/src/scylladb_mcp_server.py"],
      "env": {
        "SCYLLA_CONNECTION_MODE": "alternator",
        "SCYLLA_ALTERNATOR_ENDPOINT": "http://your-endpoint:8000",
        "AWS_ACCESS_KEY_ID": "your-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret"
      }
    }
  }
}

Claude Code Configuration

For Claude Code users, you have two options:

  1. Project-specific configuration (recommended):
    • Create a .claude/config.json file in your project root
    • This keeps MCP configuration with your project
{
  "mcpServers": {
    "scylladb": {
      "command": "python3",
      "args": ["./src/scylladb_mcp_server.py"],
      "env": {
        "SCYLLA_CONNECTION_MODE": "alternator",
        "SCYLLA_ALTERNATOR_ENDPOINT": "http://your-endpoint:8000",
        "AWS_ACCESS_KEY_ID": "your-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret"
      }
    }
  }
}
  1. Global configuration:
    • Use the same claude_desktop_config.json location as Claude Desktop
    • Configuration will be available in all Claude Code sessions

Connection Modes

  • docker - Local ScyllaDB container (default)
  • cloud - ScyllaDB Cloud with CQL
  • alternator - ScyllaDB or DynamoDB via Alternator API

DynamoDB Configuration

To connect to AWS DynamoDB for A/B testing, add these environment variables to your configuration:

{
  "mcpServers": {
    "scylladb": {
      "command": "python3",
      "args": ["/path/to/scylladb-mcp-server/src/scylladb_mcp_server.py"],
      "env": {
        "SCYLLA_CONNECTION_MODE": "alternator",
        "SCYLLA_ALTERNATOR_ENDPOINT": "http://your-scylla-endpoint:8000",
        "AWS_ACCESS_KEY_ID": "your-aws-key",
        "AWS_SECRET_ACCESS_KEY": "your-aws-secret",
        "AWS_REGION": "us-east-1",
        "DYNAMODB_ENDPOINT": ""  // Leave empty for real AWS DynamoDB
      }
    }
  }
}

For local DynamoDB testing, set DYNAMODB_ENDPOINT to your local DynamoDB URL (e.g., http://localhost:8001).

Connecting to ScyllaDB Cloud

  1. Create a ScyllaDB Cloud Account:

    • Sign up at cloud.scylladb.com
    • Choose "DynamoDB API Compatible" when creating your cluster
    • Enable "Allow Alternator API" in cluster settings

  2. Get Connection Details:

    • Find your Alternator endpoint in the cluster dashboard (e.g., http://node-0.aws-us-east-1.xxx.clusters.scylla.cloud:8000)
    • Generate API keys from the cluster settings
    • Note: ScyllaDB uses AWS-compatible authentication

  3. Test Connection:

    import boto3

dynamodb = boto3.resource('dynamodb',
    endpoint_url='http://your-endpoint:8000',
    region_name='us-east-1',
    aws_access_key_id='your-key',
    aws_secret_access_key='your-secret'
)

# List tables to verify connection
print(list(dynamodb.tables.all()))

Connecting to AWS DynamoDB

  1. Set up AWS Account:

    • Create an AWS account if you don't have one
    • Navigate to IAM console

  2. Create Access Keys:

    • Go to IAM ā†’ Users ā†’ Add User
    • Select "Programmatic access"
    • Attach policy: AmazonDynamoDBFullAccess
    • Save the Access Key ID and Secret Access Key

  3. Configure Region:

    • Choose your preferred AWS region (e.g., us-east-1)
    • DynamoDB is available in all AWS regions

  4. Test Connection:

    import boto3

# For real AWS DynamoDB (no endpoint_url needed)
dynamodb = boto3.resource('dynamodb',
    region_name='us-east-1'
)

# List tables
print(list(dynamodb.tables.all()))

Usage Examples

Live A/B Testing

Compare performance between DynamoDB and ScyllaDB for 1000 write operations

Cost Analysis with Real Workloads

Calculate costs for a FinTech platform processing 50,000 transactions/second

Analyze Existing DynamoDB Code

Analyze the DynamoDB patterns in test/dynamodb_online_shop_example.py

Migration Assessment

Check if this DynamoDB code will work with ScyllaDB:

response = table.transact_write_items(
    TransactItems=[
        {'Put': {'TableName': 'Orders', 'Item': order}},
        {'Update': {'TableName': 'Inventory', 'Key': {'id': item_id}}}
    ]
)

Running Demo Scripts

Before running demos, ensure your environment variables are set:

# For ScyllaDB Cloud
export SCYLLA_ALTERNATOR_ENDPOINT="http://your-node.clusters.scylla.cloud:8000"
export AWS_ACCESS_KEY_ID="your-scylla-key"
export AWS_SECRET_ACCESS_KEY="your-scylla-secret"

# For AWS DynamoDB (in addition to above)
export AWS_REGION="us-east-1"
# Leave DYNAMODB_ENDPOINT empty for real AWS, or set to local endpoint

Quick Performance Test

python3 src/quick_demo.py

Shows connection latency differences between platforms.

A/B Write Performance

python3 src/simple_ab_demo.py

Demonstrates identical code running on both platforms with performance metrics.

Full YCSB Benchmark

python3 src/ycsb_benchmark.py

Runs industry-standard benchmarks showing ~29% better P99 latency.

IoT Sensor Data Demo

# Run comparison between both platforms
python3 src/demo_iot_sensors.py

# Run only on ScyllaDB
python3 src/demo_iot_sensors.py scylla

# Run only on DynamoDB
python3 src/demo_iot_sensors.py dynamo

Simulates high-volume IoT sensor data ingestion.

E-commerce Platform Demo

# Run comparison
python3 src/demo_ecommerce.py

# Single platform testing
python3 src/demo_ecommerce.py scylla
python3 src/demo_ecommerce.py dynamo

Demonstrates shopping cart, inventory, and order processing patterns.

Cost Calculator Test

python3 src/test_mcp_server.py

Tests the advisor with various workload scenarios and cost calculations.

Available MCP Tools

  • connect - Connect to ScyllaDB/DynamoDB (supports all modes)
  • costEstimate - Advanced cost comparison with workload templates
  • checkMigration - Validate DynamoDB code compatibility
  • analyzeWorkload - Deep analysis of DynamoDB patterns
  • comparePerformance - Live A/B testing between platforms
  • populateData - Create test data with realistic patterns
  • analyzeDynamoDBModel - Analyze AWS data models and access patterns

Workload Templates

Pre-configured profiles for accurate cost analysis:

  • Discord-scale messaging - 50K-200K ops/sec
  • AdTech RTB - Sub-10ms latency requirements
  • Cybersecurity analytics - Write-heavy, 100K-500K ops/sec
  • FinTech platform - Payment processing scale
  • Growing e-commerce - $100M+ revenue scale

Project Structure

scylladb-mcp-server/
ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ scylladb_mcp_server.py      # Main MCP server
ā”‚   ā”œā”€ā”€ technical_advisor.py         # Engineering analysis engine
ā”‚   ā”œā”€ā”€ advanced_cost_calculator.py  # Matches official calculator
ā”‚   ā”œā”€ā”€ workload_templates.py        # Real-world profiles
ā”‚   ā”œā”€ā”€ query_analyzer.py            # DynamoDB pattern analysis
ā”‚   ā”œā”€ā”€ quick_demo.py               # Performance demos
ā”‚   ā”œā”€ā”€ simple_ab_demo.py           # A/B testing demo
ā”‚   ā”œā”€ā”€ live_ab_test.py             # Advanced comparison
ā”‚   ā”œā”€ā”€ ycsb_benchmark.py           # YCSB implementation
ā”‚   ā””ā”€ā”€ requirements.txt            # Python dependencies
ā”œā”€ā”€ test/
ā”‚   ā””ā”€ā”€ dynamodb_online_shop_example.py  # AWS sample for analysis
ā”œā”€ā”€ docs/
ā”‚   ā””ā”€ā”€ SYSTEMS_DESIGN_CONTEXT.md   # Architecture philosophy
ā”œā”€ā”€ .env.example                    # Environment template
ā”œā”€ā”€ setup.sh                        # Automated setup
ā””ā”€ā”€ README.md                       # This file

Key Results

Based on real benchmarks and customer data:

  • Cost Reduction: 86-99% depending on workload
  • P99 Latency: ~29% better under load
  • No Throttling: Hardware limits only
  • Same API: Drop-in replacement via Alternator

Technical Philosophy

Every response is backed by:

  • Actual benchmarks from scylladb.com
  • Real customer workloads (Discord, Palo Alto Networks, Comcast)
  • Transparent architecture explanations
  • No marketing claims without data

Contributing

PRs welcome for:

  • Additional workload templates
  • More DynamoDB pattern detection
  • Real migration case studies
  • Performance benchmark updates

License

[TBD]

Support