Betterdb Mcp
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
Jump to
- 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:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Betterdb McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- 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 typesQuick 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.comLicense
See LICENSE for details.Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.





