@betterdb/mcp

Give your AI assistant deep visibility into your Valkey and Redis databases. The BetterDB MCP server connects Claude Code, Cursor, Windsurf, and other MCP-compatible clients to the BetterDB monitoring platform — letting your AI query real-time metrics, diagnose slow commands, detect anomalies, and investigate incidents without leaving your editor.

Why BetterDB?

BetterDB is a monitoring and observability platform built for Valkey and Redis providing real-time dashboards, anomaly detection, and operational intelligence for your Valkey and Redis deployments. Unlike tools that only show a live snapshot, BetterDB persists historical metrics, slowlogs, and audit trails — so you can investigate what happened yesterday, not just what's happening now.

Key capabilities exposed through MCP:

• Real-time health checks — memory fragmentation, hit rate, replication lag, connected clients
• Slow command analysis — slowlog and COMMANDLOG (Valkey 8+) with pattern aggregation
• Hot key detection — find cache-busting keys via LFU frequency scores or idle time analysis
• Cluster-wide visibility — per-node stats, aggregated slowlogs, and slot-level metrics across all nodes
• Anomaly detection — Z-score analysis on memory, CPU, hit rate, and other metrics (Pro)
• Client activity tracking — connection counts, command distribution, and buffer usage over time
• ACL audit log — investigate auth failures and access patterns
• Latency event history — track latency trends for specific event types

Quick Start

1. Get a token

In BetterDB, go to Settings → MCP Tokens and generate a new token.

2. Configure your MCP client

Add to your MCP client config (e.g. Claude Code or OpenAI Codex):

{
  "mcpServers": {
    "betterdb": {
      "type": "stdio",
      "command": "npx",
      "args": ["@betterdb/mcp"],
      "env": {
        "BETTERDB_URL": "https://<your-workspace>.app.betterdb.com",
        "BETTERDB_TOKEN": "<your-token>"
      }
    }
  }
}

For local development with an existing monitor (token not required):

{
  "mcpServers": {
    "betterdb": {
      "type": "stdio",
      "command": "npx",
      "args": ["@betterdb/mcp"],
      "env": {
        "BETTERDB_URL": "http://localhost:3001"
      }
    }
  }
}

For zero-config local development (auto-starts and manages a monitor process):

{
  "mcpServers": {
    "betterdb": {
      "type": "stdio",
      "command": "npx",
      "args": ["@betterdb/mcp", "--autostart", "--persist"]
    }
  }
}

3. Start asking questions

Once connected, your AI assistant can query your databases directly:

• "What's the health of my production Valkey instance?"
• "Show me the slowest commands from the last hour"
• "Are there any hot keys causing uneven load?"
• "Which cluster node has the highest memory usage?"
• "Have there been any anomalies in the last 24 hours?"

Configuration

Environment Variables

| Variable | Default | Description | |---|---|---| | BETTERDB_URL | http://localhost:3001 | BetterDB instance URL (port depends on your Docker config) | | BETTERDB_TOKEN | — | MCP token from Settings (required for cloud, optional for local) | | BETTERDB_INSTANCE_ID | — | Pre-select a specific instance (skips select_instance) |

CLI Arguments

| Argument | Default | Description | |---|---|---| | --autostart | — | Spawn and manage a local BetterDB monitor process on startup | | --persist | — | Keep the monitor running after the MCP server exits (requires --autostart) | | --port <number> | 3001 | Port for the auto-started monitor API | | --storage <type> | sqlite | Storage backend: sqlite or memory | | --stop | — | Stop a previously persisted monitor process and exit |

Available Tools

Instance Tools

| Tool | Description | |---|---| | list_instances | List all registered Valkey/Redis instances with connection status | | select_instance | Select which instance subsequent calls operate on | | get_health | Synthetic health summary — the best starting point for any investigation | | get_info | Full INFO stats, optionally filtered by section | | get_slowlog | Recent slow commands from the slowlog buffer | | get_commandlog | Recent COMMANDLOG entries (Valkey 8+) | | get_latency | Latency event history | | get_latency_history | Detailed history for a specific latency event | | get_memory | MEMORY DOCTOR assessment and MEMORY STATS breakdown | | get_clients | Active client list with connection details | | get_hot_keys | Hot key tracking data from LFU or idle time analysis | | get_slowlog_patterns | Aggregated slowlog patterns with frequency and avg duration | | get_commandlog_history | Persisted COMMANDLOG entries with time range filtering | | get_commandlog_patterns | Aggregated COMMANDLOG patterns | | get_anomalies | Anomaly detection events (Pro) | | get_client_activity | Time-bucketed client activity from persisted snapshots | | get_acl_audit | ACL audit log entries | | get_cluster_nodes | Cluster node discovery — roles, health, slot ranges | | get_cluster_node_stats | Per-node performance stats across the cluster | | get_cluster_slowlog | Aggregated slowlog across all cluster nodes | | get_slot_stats | Per-slot key counts and CPU usage (Valkey 8+) |

Connection Management Tools

| Tool | Description | |---|---| | add_connection | Add a new Valkey/Redis connection to BetterDB | | test_connection | Test connection credentials without persisting | | remove_connection | Remove a connection from BetterDB | | set_default_connection | Set a connection as the active default |

Monitor Lifecycle Tools

| Tool | Description | |---|---| | start_monitor | Start a persistent BetterDB monitor background process | | stop_monitor | Stop a previously started persistent monitor process |

Requirements

• Node.js 20+
• A running BetterDB instance (cloud or self-hosted), or use --autostart to have the MCP server manage one automatically

Documentation

Full docs: docs.betterdb.com

License

See LICENSE for details.