MCP Server Integration with Claude Code

easy-db-lab includes a Model Context Protocol (MCP) server that allows seamless integration with Claude Code. This enables Claude to directly interact with your easy-db-lab clusters and perform operations through a standardized protocol.

Starting the MCP Server

To start the MCP server, run:

easy-db-lab server

By default, the server picks an available port. To specify a port:

easy-db-lab server --port 8888

The server automatically generates a .mcp.json configuration file in the current directory with the connection details.

Adding to Claude Code

Once the MCP server is running, start Claude Code from the same directory:

claude

Claude Code automatically detects and uses the .mcp.json file generated by the server.

Available MCP Tools

The MCP server exposes commands annotated with @McpCommand as tools to Claude. Tool names use underscores and are derived from the command's package namespace.

Cluster Lifecycle

Tool Name Description
init Initialize a directory for easy-db-lab
up Provision AWS infrastructure
cassandra_down Shut down AWS infrastructure
clean Clean up generated files
status Display full environment status
hosts List all hosts in the cluster
ip Get IP address for a host by alias

Cassandra Management

Tool Name Description
cassandra_use Select a Cassandra version
cassandra_list List available Cassandra versions
cassandra_start Start Cassandra on all nodes
cassandra_restart Restart Cassandra on all nodes
cassandra_update_config Apply configuration patch to nodes

Cassandra Stress Testing

Tool Name Description
cassandra_stress_start Start a stress job on K8s
cassandra_stress_stop Stop and delete stress jobs
cassandra_stress_status Check status of stress jobs
cassandra_stress_logs View logs from stress jobs
cassandra_stress_list List available workloads
cassandra_stress_fields List available field generators
cassandra_stress_info Show workload information

ClickHouse

Tool Name Description
clickhouse_start Deploy ClickHouse cluster to K8s
clickhouse_stop Remove ClickHouse cluster
clickhouse_status Check ClickHouse cluster status

OpenSearch

Tool Name Description
opensearch_start Create AWS OpenSearch domain
opensearch_stop Delete OpenSearch domain
opensearch_status Check OpenSearch domain status

Spark

Tool Name Description
spark_submit Submit Spark job to EMR cluster
spark_status Check status of a Spark job
spark_jobs List recent Spark jobs
spark_logs Download EMR logs from S3

Kubernetes

Tool Name Description
k8_apply Apply observability stack to K8s

Utilities

Tool Name Description
prune_amis Prune older private AMIs

Tool Naming Convention

MCP tool names are derived from the command's package location: - Top-level commands: status, hosts, ip, clean, init, up - Cassandra commands: cassandra_ prefix (e.g., cassandra_start, cassandra_use) - Nested commands: cassandra_stress_ prefix (e.g., cassandra_stress_start) - Hyphens become underscores: update-config → cassandra_update_config

Benefits of MCP Integration

Benefit Description
Direct Control Claude executes easy-db-lab commands directly without manual intervention
Context Awareness Claude maintains context about your cluster state and configuration
Automation Complex multi-step operations can be automated through Claude
Intelligent Assistance Claude can analyze logs, metrics, and provide optimization recommendations

Example Workflow

  1. Start the MCP server in one terminal: easy-db-lab server

  2. In another terminal, start Claude Code from the same directory: claude Claude Code automatically detects the .mcp.json file generated by the server.

  3. Ask Claude to help manage your cluster:

  4. "Initialize a new 5-node Cassandra cluster with i4i.xlarge instances"
  5. "Check the status of all nodes"
  6. "Select Cassandra version 5.0 and start it"
  7. "Start a KeyValue stress test for 1 hour"
  8. "Show me the stress job logs"
  9. "Deploy ClickHouse and check its status"

Notes