Monitor

io.github.BetterDB-incPublished by GitHub account BetterDB-incv0.1.4Updated Oct 24, 2026

BetterDB MCP server - Valkey observability for Claude Code and other MCP clients

VerifiedSTDIODesktop onlyDatabasesSecurity & MonitoringAI & ML

Overview

AI-generated overview

Connects an AI assistant to the BetterDB monitoring platform so it can inspect Valkey and Redis health, slow commands, hot keys, clusters and AI cache metrics.

What you can do
  • List and select monitored Valkey/Redis instances, then pull health summaries, INFO stats, memory diagnostics and client lists
  • Inspect slowlog and COMMANDLOG entries, aggregated patterns, latency event history, hot keys and ACL audit logs
  • Review cluster node roles, per-node stats, cluster-wide slowlogs and per-slot metrics
  • Forecast capacity and latency regressions, and check vector index health and search latency
  • Explore AI observability data: AI component instances, OpenTelemetry traces and trace-to-Valkey correlation
  • Manage caches and connections: cache health and threshold recommendations, propose/approve/reject cache changes, add or remove connections, start or stop a monitor
When to use it
Useful when you run Valkey or Redis and want an assistant to diagnose performance problems, investigate incidents, or tune semantic and agent caches from inside the editor instead of switching to dashboards.
Requirements
Node.js 20 or newer, run locally via npx. A running BetterDB instance (cloud or self-hosted) set through BETTERDB_URL, or the --autostart flag to let the server manage one. BETTERDB_TOKEN is required for cloud and optional for self-hosted; BETTERDB_INSTANCE_ID optionally pre-selects an instance.
Before you install
BETTERDB_TOKEN is a secret generated in BetterDB settings and grants access as its owner; write tools need an admin token and actions are logged under that owner. Approving a cache proposal applies the change to Valkey immediately, and connection tools add or remove monitored connections. Some features (anomaly detection, latency regressions, largest keys, SLA fields) require a Pro plan.

Installation

In SourceWeft

  1. Open Monitor in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@betterdb/mcp

[npm version] [total downloads] [license: MIT] [types] [GitHub stars]

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.

[AI Cache & Memory tab in BetterDB Monitor]

[AI Traces waterfall in BetterDB Monitor]

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

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 with an existing monitor (token not required):

json
{  "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):

json
{  "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

VariableDefaultDescription
BETTERDB_URLhttp://localhost:3001BetterDB 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_INSTANCE_ID—Pre-select a specific instance (skips select_instance)

CLI Arguments

ArgumentDefaultDescription
--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>3001Port for the auto-started monitor API
--storage <type>sqliteStorage backend: sqlite or memory
--stop—Stop a previously persisted monitor process and exit

Available Tools

Instance Tools

ToolDescription
list_instancesList all registered Valkey/Redis instances with connection status
select_instanceSelect which instance subsequent calls operate on
get_healthSynthetic health summary — the best starting point for any investigation
get_infoFull INFO stats, optionally filtered by section
get_slowlogRecent slow commands from the slowlog buffer
get_commandlogRecent COMMANDLOG entries (Valkey 8+)
get_latencyLatency event history
get_latency_historyDetailed history for a specific latency event
get_memoryMEMORY DOCTOR assessment and MEMORY STATS breakdown
get_clientsActive client list with connection details
get_hot_keysHot key tracking data from LFU or idle time analysis
get_slowlog_patternsAggregated slowlog patterns with frequency and avg duration
get_commandlog_historyPersisted COMMANDLOG entries with time range filtering
get_commandlog_patternsAggregated COMMANDLOG patterns
get_anomaliesAnomaly detection events (Pro)
get_retry_amplificationLive retry-amplification state, last episode and top clients (Pro)
get_client_activityTime-bucketed client activity from persisted snapshots
get_acl_auditACL audit log entries
get_cluster_nodesCluster node discovery — roles, health, slot ranges
get_cluster_node_statsPer-node performance stats across the cluster
get_cluster_slowlogAggregated slowlog across all cluster nodes
get_slot_statsPer-slot key counts and CPU usage (Valkey 8+)

Analytics Tools

ToolDescription
get_forecastCapacity forecast for a metric (opsPerSec, usedMemory, cpuTotal, memFragmentation) with projected time to ceiling
get_latency_regressionsDetected sustained p99 latency regressions vs baseline from the anomaly store (Pro)
get_replication_divergencePer-replica offset gap series and divergence events for a primary (Pro)
get_largest_keysLargest keys by measured memory usage from key analytics snapshots (Pro)
get_incident_timelineAnomaly incidents as ordered timelines with matched sequence patterns and recovery status (Pro)

Vector Search Tools

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

ToolDescription
get_vector_indexesPer-index health: document count, memory usage, indexing failures, and percent indexed
get_inference_latencyFT.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.

ToolDescription
ai_list_instancesSuperset discovery view of all AI component instances with liveness and latest metrics sample
ai_instance_historyStored metrics time-series for one AI component instance (hit rate, cost saved, evictions, threshold, …)
list_ai_tracesList recent AI application traces (LLM calls, cache lookups, memory recalls, retrieval spans)
get_ai_traceFull span waterfall for one trace with timing, parent relationships, and attributes
correlate_ai_traceJoin a trace's cache/memory spans with live Valkey state to explain misses or stale recalls

Connection Management Tools

ToolDescription
add_connectionAdd a new Valkey/Redis connection to BetterDB
test_connectionTest connection credentials without persisting
remove_connectionRemove a connection from BetterDB
set_default_connectionSet a connection as the active default

Monitor Lifecycle Tools

ToolDescription
start_monitorStart a persistent BetterDB monitor background process
stop_monitorStop 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:

ToolDescription
cache_listList all caches registered for the active instance with hit rate and total ops
cache_healthDetailed health for one cache; response branches on cache_type (semantic_cache vs agent_cache)
cache_threshold_recommendationThreshold-tuning recommendation for a semantic_cache, derived from the rolling similarity window
cache_tool_effectivenessPer-tool hit rate, cost saved, and TTL recommendation for an agent_cache
cache_similarity_distributionHistogram of recent similarity scores for a semantic_cache (20 buckets, width 0.1)
cache_recent_changesRecent proposals (any status) for a single cache, so agents can avoid re-proposing

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

ToolDescription
cache_propose_threshold_adjustPropose a similarity-threshold change on a semantic_cache (per-category or global)
cache_propose_tool_ttl_adjustPropose a per-tool TTL change on an agent_cache
cache_propose_invalidatePropose an invalidation; filter shape branches on cache type

Approve / reject / list:

ToolDescription
cache_list_pending_proposalsList pending proposals on the active instance, optionally filtered by cache_name
cache_get_proposalFetch a single proposal by id, including its audit trail
cache_approve_proposalApprove a pending proposal; synchronously applies the change to Valkey
cache_reject_proposalReject a pending proposal with an optional reason
cache_edit_and_approve_proposalEdit 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

Documentation

Full docs: docs.betterdb.com

License

See LICENSE for details.

Source: packages/mcp/README.md at commit b8ac28a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.4LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.