Betterdb Mcp

by BetterDB-inc

445 downloads
Not rated
GitHub

About

MCP server for Valkey and Redis observability. Query real-time health, slow commands, hot keys, anomaly detection, and cluster analytics directly from your AI assistant.

Details

Author
BetterDB-inc
Downloads
445
Categories
Other, Infrastructure, Database

- Real-time health checks for memory, hit rate, and replication lag
- Slow command analysis with pattern aggregation
- Hot key detection via LFU or idle time analysis
- Cluster-wide visibility across all nodes
- Anomaly detection using Z-score analysis (Pro)
- Latency event history and ACL audit logs

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Betterdb Mcp
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Generate an MCP token in BetterDB (Settings → MCP Tokens), then add the server to your MCP client config using npx @betterdb/mcp with the BETTERDB_URL and BETTERDB_TOKEN environment variables. Once connected, ask natural-language questions about your database health, slow commands, hot keys, and anomalies.

list_instances

List all Valkey/Redis instances registered in BetterDB. Shows connection status and capabilities.

select_instance

Select which instance subsequent tool calls operate on.

add_connection

Add a new Valkey/Redis connection to BetterDB. Optionally set it as the active default.

test_connection

Test a Valkey/Redis connection without persisting it. Use before add_connection to validate credentials.

remove_connection

Remove a connection from BetterDB.

set_default_connection

Set a connection as the active default for BetterDB.

get_info

Get INFO stats for the active instance. Contains all health data: memory, clients, replication, keyspace, stats (hit rate, ops/sec), and server info. Optionally filter to a section: server|clients|memory|stats|replication|keyspace.

get_slowlog

Get the most recent slow commands from the slowlog.

get_commandlog

Get the most recent entries from COMMANDLOG (Valkey 8+ only, superset of slowlog).

get_latency

Get latency event history for the active instance.

get_memory

Get memory diagnostics: MEMORY DOCTOR assessment and MEMORY STATS breakdown.

get_clients

Get the active client list with connection details.

get_health

Get a synthetic health summary for the active instance: keyspace hit rate, memory fragmentation ratio, connected clients, replication lag (replicas only), and keyspace size. Use this as the first call when investigating an instance — it surfaces the most actionable signals without requiring you to parse raw INFO output.

get_slowlog_patterns

Get analyzed slowlog patterns from persisted storage. Groups slow commands by normalized pattern, showing frequency, average duration, and example commands. Survives slowlog buffer rotation — data goes back as far as BetterDB has been running.

get_commandlog_history

Get persisted COMMANDLOG entries from storage (Valkey 8+ only). Supports time range filtering to investigate specific incidents. Returns empty with a note if COMMANDLOG is not supported on this instance.

get_commandlog_patterns

Get analyzed COMMANDLOG patterns from persisted storage (Valkey 8+ only). Like get_slowlog_patterns but includes large-request and large-reply patterns in addition to slow commands.

get_anomalies

Get anomaly detection events from persisted storage. BetterDB continuously runs Z-score analysis on memory, hit rate, CPU, and other metrics — this returns the detected anomalies. Use to investigate what triggered an alert or correlate with an incident.

get_client_activity

Get time-bucketed client activity from persisted snapshots. Shows connection counts, command distribution, and buffer usage over time. Use startTime/endTime to focus on a specific incident window.

get_hot_keys

Get hot key tracking data from persisted storage. BetterDB periodically scans keys using LFU frequency scores (when maxmemory-policy is an LFU variant) or OBJECT IDLETIME / COMMANDLOG-derived frequency. Each snapshot captures the top keys ranked by access frequency. Use this to find cache-busting keys, uneven access patterns, or keys that dominate throughput. The signalType field in each entry indicates which detection mode was active (lfu or idletime).

get_cluster_nodes

Discover all nodes in the Valkey cluster — role (master/replica), address, health status, and slot ranges. Returns an error message if this instance is not running in cluster mode.

get_cluster_node_stats

Get per-node performance stats: memory usage, ops/sec, connected clients, replication offset, and CPU. Use this to identify hot nodes, lagging replicas, or uneven load distribution.

get_cluster_slowlog

Get the aggregated slowlog across ALL nodes in the cluster. This is the primary tool for finding slow commands in cluster mode — per-node slowlogs are incomplete. Returns an error message if not in cluster mode.

get_slot_stats

Get per-slot key counts and CPU usage (Valkey 8.0+ only). Use orderBy='cpu-usec' to find hot slots, or 'key-count' to find the most populated slots. Returns an error message if not supported.

get_latency_history

Get the full latency history for a named event (e.g. 'command', 'fast-command'). Call get_latency first to see which event names are available, then use this to investigate a specific event's trend over time.

get_acl_audit

Get persisted ACL audit log entries from storage. Filter by username, reason (auth, command, key, channel), or time range. Use this to investigate why a connection is failing or audit access patterns.

start_monitor

Start the BetterDB monitor as a persistent background process. If already running, returns the existing URL. The monitor persists across MCP sessions and must be stopped explicitly with stop_monitor.

cache_list

List all caches (semantic_cache and agent_cache) registered for the active instance, with hit rate and total ops.

cache_health

Detailed health for a single cache. Response branches by type: semantic_cache reports category_breakdown + uncertain_hit_rate; agent_cache reports tool_breakdown.

cache_threshold_recommendation

Threshold-tuning recommendation for a semantic_cache, based on the rolling similarity-score window. Errors with INVALID_CACHE_TYPE on agent_cache.

cache_tool_effectiveness

Per-tool hit rate, cost saved, and TTL recommendation for an agent_cache. Errors with INVALID_CACHE_TYPE on semantic_cache.

cache_similarity_distribution

Histogram of recent similarity scores (20 buckets, width 0.1) for a semantic_cache. Errors on agent_cache.

cache_recent_changes

Recent proposals for a single cache (any status), so agents can avoid re-proposing pending or recently-applied changes. Newest first.

cache_propose_threshold_adjust

Propose a semantic-cache similarity-threshold change for review. Creates a pending proposal that requires human approval before any change is applied. Reasoning must be at least 20 characters.

cache_propose_tool_ttl_adjust

Propose an agent-cache per-tool TTL change for review. Creates a pending proposal that requires human approval. Reasoning must be at least 20 characters.

cache_propose_invalidate

Propose a cache invalidation for review. Filter shape depends on cache type: semantic_cache requires filter_kind=valkey_search + filter_expression; agent_cache requires filter_kind in (tool|key_prefix|session) + filter_value. Warns when estimated_affected exceeds 10000.

cache_list_pending_proposals

List pending cache proposals for the active instance, newest first. Optionally filter by cache_name.

cache_get_proposal

Fetch a single cache proposal by id, including its audit trail.

cache_approve_proposal

Approve a pending proposal. Synchronously applies the change to Valkey and returns the terminal status (applied|failed). Idempotent: a second call on an already-applied proposal returns the cached result.

cache_reject_proposal

Reject a pending proposal. Optionally records a reason in the audit trail.

cache_edit_and_approve_proposal

Edit an existing pending proposal and approve it in one step. Provide exactly one edit field matching the proposal type: new_threshold for threshold_adjust, new_ttl_seconds for tool_ttl_adjust. Invalidate proposals are not editable.

stop_monitor

Stop a persistent BetterDB monitor process that was previously started with start_monitor or --autostart --persist.

memory_stores

List agent-memory stores discovered on an instance (name, capabilities, stats key).

memory_list

List memories in a store, newest first, with optional scope and tag filters.

memory_get

Fetch a single memory by ID from a store.

memory_stats

Get item count, eviction count, and live config for a memory store.

memory_recall

Recall memories from a store by a precomputed query vector (the caller supplies the embedding).

memory_forget

Propose forgetting memories (by id, or by scope/tags). Creates a pending proposal that a human must approve before anything is deleted.

memory_list_pending_forgets

List pending forget proposals awaiting approval on an instance.

memory_approve_forget

Approve a pending forget proposal, applying the deletion against the live store.

memory_reject_forget

Reject a pending forget proposal without deleting anything.

ai_list_instances

List AI component instances (semantic caches, agent caches, agent memory stores, retrieval pipelines) auto-discovered on the connected Valkey/Redis instance, with liveness and the latest stored metrics sample. This is the superset discovery view across all AI components — use cache_list for cache-specific live stats and memory_stores for memory-store details. Use the returned instance field value as the field parameter of ai_instance_history.

ai_instance_history

Get the stored metrics time-series for one AI component instance (hits, misses, hit rate, cost saved, evictions, item count, index size, threshold). Use ai_list_instances first to find the instance field identifier. Use this to see trends: hit-rate degradation, growth, threshold drift.

list_ai_traces

List recent AI application traces ingested via OpenTelemetry (LLM calls, cache lookups, memory recalls, retrieval spans). Not tied to a Valkey instance — traces come from instrumented AI apps. Use get_ai_trace for a full span waterfall and correlate_ai_trace to join a trace with live Valkey state.

get_ai_trace

Get the full span waterfall for one AI trace: every span with timing, parent relationships, and attributes (model, cache hit/miss, similarity scores). Use list_ai_traces to find trace IDs.

correlate_ai_trace

Explain WHY a trace behaved the way it did by joining its cache/memory spans with live Valkey state: does the key still exist, what is its TTL, what threshold was active, what is the index state. The strongest tool for diagnosing unexpected cache misses or stale memory recalls. Requires a selected instance (the one the AI components run on).

get_forecast

Get a capacity forecast for one metric: current trajectory and projected time until the resource ceiling is hit. Metric kinds: opsPerSec, usedMemory, cpuTotal, memFragmentation. Use for capacity planning ("when does memory run out at current growth?").

get_latency_regressions

Get detected latency regressions (sustained p99 command-latency degradations vs baseline) from persisted storage. Companion to get_anomalies: same event store, pre-filtered to latency regressions. Use when investigating "the database got slower".

get_largest_keys

Get the largest keys from key analytics snapshots, ranked by measured memory usage. Coverage note: snapshots track the biggest collections by element count, so a memory-heavy key with few elements may not be tracked. Companion to get_hot_keys, which ranks by access frequency. Use to find memory hogs, bloated hashes/sets, or candidates for TTL/eviction. Requires BetterDB Pro (keyAnalytics).

get_vector_indexes

Get health details for every vector search index on the instance: document count, memory usage, indexing failures, and percent indexed. Requires the Search module (valkey-search / RediSearch) on the connection — errors clearly if absent. Use to diagnose incomplete indexing or index memory growth.

get_inference_latency

Get the FT.SEARCH latency profile: p50/p95/p99 per vector index over the sampling window, plus SLA breach status per index. sla is null when BetterDB Pro inference SLA monitoring is absent or unlicensed, and an empty array when it is active with no indexes configured. More specific than get_latency, which covers general command latency. Use to answer "are vector searches meeting their latency budget?".

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

@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): ``json { "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 (token not required): `json { "mcpServers": { "betterdb": { "type": "stdio", "command": "npx", "args": ["@betterdb/mcp"], "env": { "BETTERDB_URL": "http://localhost:3001" } } } } `

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 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) |

Available 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+) |

Requirements

- Node.js 20+ - A running BetterDB instance (cloud or self-hosted)

Documentation

Full docs: docs.betterdb.com

License

See LICENSE for details.
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.