Monitor

io.github.BetterDB-inc由 GitHub 账号 BetterDB-inc 发布v0.1.4更新于 Oct 24, 2026

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

已验证STDIO仅桌面数据库安全与监控AI 与机器学习

概览

AI 生成的概览

把 AI 助手接入 BetterDB 监控平台，用于查看 Valkey 与 Redis 的健康状况、慢命令、热键、集群状态和 AI 缓存指标。

可以做什么
  • 列出并选择受监控的 Valkey/Redis 实例，获取健康摘要、INFO 统计、内存诊断和客户端列表
  • 查看 slowlog 与 COMMANDLOG 记录、聚合模式、延迟事件历史、热键和 ACL 审计日志
  • 查看集群节点角色、单节点统计、跨集群慢日志和按槽位指标
  • 预测容量与延迟回归，检查向量索引健康度和搜索延迟
  • 浏览 AI 可观测数据：AI 组件实例、OpenTelemetry 追踪，以及追踪与 Valkey 状态的关联
  • 管理缓存与连接：缓存健康与阈值建议、提出/批准/拒绝缓存变更、增删连接、启动或停止监控进程
适用场景
适合运行 Valkey 或 Redis 的团队，希望助手在编辑器内诊断性能问题、排查故障，或调整语义缓存与智能体缓存，而不必切换到监控面板。
运行要求
需要 Node.js 20 或更高版本，通过 npx 在本地运行。需要一个运行中的 BetterDB 实例（云端或自托管）并通过 BETTERDB_URL 指定，或使用 --autostart 让服务器自行管理实例。云端必须提供 BETTERDB_TOKEN，自托管可选；BETTERDB_INSTANCE_ID 可预选实例。
安装前请注意
BETTERDB_TOKEN 是在 BetterDB 设置中生成的密钥，以其所有者身份访问；写操作工具需要管理员令牌，操作会记录在该所有者名下。批准缓存提案会立即将变更应用到 Valkey，连接工具会新增或删除受监控连接。异常检测、延迟回归、最大键和 SLA 字段等功能需要 Pro 方案。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Monitor，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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.

来源：packages/mcp/README.md，提交 b8ac28a

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.1.4最新Sep 16, 2026

评分

已满足适用检查项的 40%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。