@betterdb/mcp

total downloads

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.

See it live in BetterDB Monitor

BetterDB Monitor gives you live dashboards for the AI workloads running on your Valkey:

• AI Cache & Memory - hit rate, cost saved, evictions, and index size across all your caches and memory stores, with history.
• AI Traces - OpenTelemetry waterfalls for each request, correlated with live Valkey state to explain every cache hit and miss.

Run it self-hosted (docker run -p 3001:3001 betterdb/monitor), or use BetterDB Cloud - which can also provision a managed, TLS-enabled Valkey instance (Search module included) in one click.

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?"
• "Tune the threshold on my faq-cache — propose a change for me to review"
• "Why is the weather_lookup tool's hit rate so low?"

Configuration

Environment Variables

CLI Arguments

Available Tools

Instance Tools

Analytics Tools

Vector Search Tools

For deployments running the Search module (valkey-search / RediSearch).

AI Observability Tools

For AI components (semantic caches, agent caches, agent-memory stores, retrieval pipelines) and traces ingested via OpenTelemetry.

Connection Management Tools

Monitor Lifecycle Tools

Cache Intelligence Tools

For deployments running @betterdb/semantic-cache or @betterdb/agent-cache. Caches register themselves in a Valkey-side discovery hash; Monitor exposes them through the tools below.

Read-only:

Propose changes (advisory — no Valkey writes until approved):

Approve / reject / list:

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.