Server

easy-db-lab includes a server mode that provides AI assistant integration via MCP (Model Context Protocol), REST status endpoints, and live metrics streaming. This enables Claude to directly interact with your clusters, and provides programmatic access to cluster status.

The server exposes tools for all supported databases — Cassandra, ClickHouse, OpenSearch, and Spark — as well as cluster lifecycle management and observability.

Starting the Server

To start the 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 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 Tools

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

Cluster Lifecycle

Cassandra Management

Cassandra Stress Testing

ClickHouse

OpenSearch

Spark

Kubernetes

Utilities

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

Example Workflow

1. Start the 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:

   • "Initialize a new 5-node cluster with i4i.xlarge instances"
   • "Check the status of all nodes"
   • "Select Cassandra version 5.0 and start it"
   • "Start a KeyValue stress test for 1 hour"
   • "Deploy ClickHouse and check its status"
   • "Create an OpenSearch domain and monitor its progress"
   • "Submit a Spark job to the EMR cluster"

Live Metrics Streaming

When Redis is configured via the EASY_DB_LAB_REDIS_URL environment variable, the server publishes live cluster metrics to the Redis pub/sub channel every 5 seconds. Metrics are queried from VictoriaMetrics using the same PromQL expressions as the Grafana dashboards.

Enabling

export EASY_DB_LAB_REDIS_URL=redis://localhost:6379/easydblab-events
easy-db-lab server

Metrics events are published to the same channel as command events. Consumers filter by the event.type field.

Event Types

Only metrics for running services are published. If the cluster is running ClickHouse instead of Cassandra, no Cassandra metrics events are emitted.

Metrics.System

Published every 5 seconds with per-node CPU, memory, disk I/O, and filesystem metrics:

{
  "timestamp": "2026-03-08T14:22:05.123Z",
  "commandName": "server",
  "event": {
    "type": "Metrics.System",
    "nodes": {
      "db-0": {
        "cpuUsagePct": 34.2,
        "memoryUsedBytes": 17179869184,
        "diskReadBytesPerSec": 52428800.0,
        "diskWriteBytesPerSec": 104857600.0,
        "filesystemUsedPct": 45.2
      },
      "db-1": {
        "cpuUsagePct": 28.7,
        "memoryUsedBytes": 16106127360,
        "diskReadBytesPerSec": 41943040.0,
        "diskWriteBytesPerSec": 83886080.0,
        "filesystemUsedPct": 42.8
      }
    }
  }
}

Metrics.Cassandra

Published every 5 seconds when the cluster is running Cassandra:

{
  "timestamp": "2026-03-08T14:22:05.187Z",
  "commandName": "server",
  "event": {
    "type": "Metrics.Cassandra",
    "readP99Ms": 1.247,
    "writeP99Ms": 0.832,
    "readOpsPerSec": 15234.5,
    "writeOpsPerSec": 12087.3,
    "compactionPending": 3,
    "compactionCompletedPerSec": 1.5,
    "compactionBytesWrittenPerSec": 52428800.0
  }
}

Field Reference

System — per node:

Cassandra — cluster-wide:

Notes

• The server requires Docker to be installed
• Your AWS profile must be configured (easy-db-lab setup-profile)
• The server runs in the foreground and logs to stdout
• Use Ctrl+C to stop the server