The BetterDB MCP server (@betterdb/mcp) provides Valkey observability for Claude Code and other MCP clients. It focuses on metrics, monitoring, and observability, with topics indicating support for Prometheus alongside Redis/Valkey-related use.
π οΈ Key Features
Valkey observability for Claude Code and other MCP clients
Metrics, monitoring, and observability
Mentions Prometheus, Redis, and Valkey in topics
π Use Cases
Collecting and viewing metrics from Valkey for AI-assisted workflows
Integrating Valkey observability into MCP-based toolchains (e.g., Claude Code)
β‘ Developer Benefits
Designed for MCP clients, including Claude Code
Package: @betterdb/mcp (MIT license); includes type support (per βtypesβ badge)
β οΈ Limitations
The provided documentation excerpt does not describe specific tools, configuration, or endpoints (toolCount not provided).
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
In Claude Code, install the BetterDB plugin and enter your URL and token when prompted:
bash
claude plugin marketplace add https://raw.githubusercontent.com/BetterDB-inc/monitor/master/.claude-plugin/marketplace.json
claude plugin install betterdb@betterdb
For other clients such as OpenAI Codex, or to configure Claude Code by hand, add to your MCP client config:
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?"
Skills
Clients that load skills from a plugin (Connect Apps and other skill-aware clients) pick these up from skills/<name>/SKILL.md. They are playbooks for the tools above: which call to make, which arguments a time window needs, and how to read a license sentence or an empty list.
Skill
Use when
betterdb-triage
"Is this instance healthy?" or any question before an instance is selected
betterdb-slow-commands
Slowest commands in a time window
betterdb-hot-keys
Hot keys or uneven key access
betterdb-memory
Fragmentation, MEMORY DOCTOR, or time to the memory ceiling
betterdb-latency
What is slow, fork time, or a latency regression
betterdb-durability
What a crash would lose, last save, replicas, or cluster vs standalone
betterdb-cache-miss
Cache hit rate, a trace, or vector index health
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 β MCP Tokens. Required for cloud. Optional for self-hosted: without it, read tools work anonymously; with it, calls act as the token's owner (write tools need an admin's token) and changes they make are recorded under the owner's name in the activity log. Tokens cannot manage members or other tokens
BETTERDB_LOCAL_TOKEN
β
Token for a monitor started with --autostart or start_monitor when BETTERDB_URL is set to a different monitor. Without it, that monitor gets no token. BETTERDB_TOKEN is used when BETTERDB_URL is unset or points at the started monitor
BETTERDB_INSTANCE_ID
β
Pre-select a specific instance (skips select_instance)
BETTERDB_TELEMETRY
on
Set to false, 0, no or off to turn off telemetry: the MCP server's tool usage events, and a monitor started with --autostart or start_monitor. Usage events (tool name, success, duration, up to 200 characters of error text) go to the monitor the call was made against, which relays them to BetterDB when its own telemetry is on
BETTERDB_MCP_TELEMETRY
β
Same values as BETTERDB_TELEMETRY, for the MCP server's usage events only. Usage events are off if either variable is off; neither turns them back on
BETTERDB_MONITOR_<NAME>
β
Passed to a monitor started with --autostart or start_monitor as <NAME>, overriding the inherited value. PORT and STORAGE_TYPE come from --port and --storage instead
CLI Arguments
Argument
Default
Description
--autostart
β
Spawn and manage a local BetterDB monitor process on startup. It inherits the MCP server's environment, except BETTERDB_URL, BETTERDB_TOKEN, BETTERDB_LOCAL_TOKEN, BETTERDB_INSTANCE_ID and BETTERDB_MCP_TELEMETRY
--no-monitor-tools
β
Do not register start_monitor and stop_monitor
--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_retry_amplification
Live retry-amplification state, last episode and top clients (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, state (healthy, suspect or failed), slot ranges, plus availability zone and shard id on Valkey 9.1+ (older versions: the zone from the connection's zone map)
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+)
Analytics Tools
Tool
Description
get_forecast
Capacity forecast for a metric (opsPerSec, usedMemory, cpuTotal, memFragmentation) with projected time to ceiling
get_latency_regressions
Detected sustained p99 latency regressions vs baseline from the anomaly store (Pro)
get_replication_divergence
Per-replica offset gap series and divergence events for a primary (Pro)
get_largest_keys
Largest keys by measured memory usage from key analytics snapshots (Pro)
get_incident_timeline
Anomaly incidents as ordered timelines with matched sequence patterns and recovery status (Pro)
Vector Search Tools
For deployments running the Search module (valkey-search / RediSearch).
FT.SEARCH p50/p95/p99 per vector index plus SLA breach status (SLA fields require Pro)
AI Observability Tools
For AI components (semantic caches, agent caches, agent-memory stores, retrieval pipelines) and traces ingested via OpenTelemetry.
Tool
Description
ai_list_instances
Superset discovery view of all AI component instances with liveness and latest metrics sample
ai_instance_history
Stored metrics time-series for one AI component instance (hit rate, cost saved, evictions, threshold, β¦)
list_ai_traces
List recent AI application traces (LLM calls, cache lookups, memory recalls, retrieval spans)
get_ai_trace
Full span waterfall for one trace with timing, parent relationships, and attributes
correlate_ai_trace
Join a trace's cache/memory spans with live Valkey state to explain misses or stale recalls
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
Registered unless --no-monitor-tools is set. start_monitor runs npx --yes @betterdb/monitor as a background process and switches the session to it. The token for a monitor the server switches to (with --autostart or start_monitor) is BETTERDB_TOKEN when BETTERDB_URL is unset or points at that monitor (localhost, 127.0.0.1 and ::1 count as the same host), and BETTERDB_LOCAL_TOKEN otherwise. The selected instance follows the same rule with BETTERDB_INSTANCE_ID. stop_monitor switches back to the previous monitor, token and instance.
Tool
Description
start_monitor
Start a persistent BetterDB monitor background process
stop_monitor
Stop a previously started persistent monitor process
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:
Tool
Description
cache_list
List all caches registered for the active instance with hit rate and total ops
cache_health
Detailed health for one cache; response branches on cache_type (semantic_cache vs agent_cache)
cache_threshold_recommendation
Threshold-tuning recommendation for a semantic_cache, derived from the rolling similarity window
cache_tool_effectiveness
Per-tool hit rate, cost saved, and TTL recommendation for an agent_cache
cache_similarity_distribution
Histogram of recent similarity scores for a semantic_cache (20 buckets, width 0.1)
cache_recent_changes
Recent proposals (any status) for a single cache, so agents can avoid re-proposing
Propose changes (advisory β no Valkey writes until approved):
Tool
Description
cache_propose_threshold_adjust
Propose a similarity-threshold change on a semantic_cache (per-category or global)
cache_propose_tool_ttl_adjust
Propose a per-tool TTL change on an agent_cache
cache_propose_invalidate
Propose an invalidation; filter shape branches on cache type
Approve / reject / list:
Tool
Description
cache_list_pending_proposals
List pending proposals on the active instance, optionally filtered by cache_name
cache_get_proposal
Fetch a single proposal by id, including its audit trail
cache_approve_proposal
Approve a pending proposal; synchronously applies the change to Valkey
cache_reject_proposal
Reject a pending proposal with an optional reason
cache_edit_and_approve_proposal
Edit a proposal's value (threshold or TTL) and approve in one step; invalidate proposals are not editable
Requirements
Node.js 20+
A running BetterDB instance (cloud or self-hosted), or use --autostart to have the MCP server manage one automatically
MCP authentication token generated from the BetterDB Settings page
BETTERDB_INSTANCE_ID
Instance ID to target when using multi-instance cloud deployments
BETTERDB_LOCAL_TOKENsecret
Token for a monitor started with --autostart or start_monitor when BETTERDB_URL is set to a different monitor; without it that monitor gets no token. BETTERDB_TOKEN is used when BETTERDB_URL is unset or points at the started monitor
BETTERDB_MCP_TELEMETRY
Set to false, 0, no or off to stop posting tool usage events to the monitor. Usage events are off if this or BETTERDB_TELEMETRY is off
BETTERDB_TELEMETRY
Set to false, 0, no or off to turn off telemetry for both the MCP server and a monitor it starts