Betterdb Mcp

@betterdb/mcp

让 AI 助手深入了解你的 Valkey 和 Redis 数据库。BetterDB MCP 服务将 Claude Code、Cursor、Windsurf 和其他兼容 MCP 的客户端连接到 BetterDB 监控平台，让你的 AI 无需离开编辑器即可查询实时指标、诊断慢速命令、检测异常并调查事故。

在 BetterDB Monitor 中查看实时数据

BetterDB Monitor 为 Valkey 上运行的 AI 工作负载提供实时仪表盘：

• AI 缓存与记忆 - 查看所有缓存和记忆存储的命中率、节省的成本、驱逐次数和索引大小，并查看历史数据。
• AI 跟踪 - 查看每个请求的 OpenTelemetry 瀑布图，并与实时 Valkey 状态关联，以解释每次缓存命中和未命中。

你可以自行托管运行（docker run -p 3001:3001 betterdb/monitor），也可以使用 BetterDB Cloud——只需单击一下，即可配置一个托管的、启用了 TLS 的 Valkey 实例（包含 Search 模块）。

为什么选择 BetterDB？

BetterDB 是一个专为 Valkey 和 Redis 打造的监控与可观测性平台，为 Valkey 和 Redis 部署提供实时仪表盘、异常检测和运维智能。与只显示实时快照的工具不同，BetterDB 会持久保存历史指标、慢日志和审计跟踪，因此你可以调查昨天发生的情况，而不仅仅是当前正在发生的情况。

通过 MCP 提供的主要功能：

• 实时健康检查 — 内存碎片率、命中率、复制延迟和已连接客户端
• 慢速命令分析 — 慢日志和 COMMANDLOG（Valkey 8+），并支持模式聚合
• 热点键检测 — 通过 LFU 频率分数或空闲时间分析，查找导致缓存失效的键
• 集群范围可见性 — 所有节点的单节点统计数据、聚合慢日志和槽级指标
• 异常检测 — 对内存、CPU、命中率和其他指标进行 Z 分数分析 (Pro)
• 客户端活动跟踪 — 跟踪连接数、命令分布和缓冲区使用情况随时间的变化
• ACL 审计日志 — 调查身份验证失败和访问模式
• 延迟事件历史记录 — 跟踪特定事件类型的延迟趋势

快速开始

1. 获取令牌

在 BetterDB 中，前往 设置 → MCP 令牌 并生成新令牌。

2. 配置 MCP 客户端

将以下内容添加到 MCP 客户端配置中（例如 Claude Code 或 OpenAI Codex）：

{
  "mcpServers": {
    "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": "http://localhost:3001"
      }
    }
  }
}

进行零配置本地开发（自动启动并管理监控进程）：

{
  "mcpServers": {
    "betterdb": {
      "type": "stdio",
      "command": "npx",
      "args": ["@betterdb/mcp", "--autostart", "--persist"]
    }
  }
}

3. 开始提问

连接后，你的 AI 助手可以直接查询数据库：

• “我的生产环境 Valkey 实例运行状况如何？”
• “显示过去一小时最慢的命令”
• “有没有导致负载不均的热点键？”
• “哪个集群节点的内存使用率最高？”
• “过去 24 小时内有没有出现异常？”
• “调整我的 faq-cache 的阈值——提出一项更改供我审核”
• “weather_lookup 工具的命中率为什么这么低？”

配置

环境变量

变量	默认值	描述
BETTERDB_URL	http://localhost:3001	BetterDB 实例 URL（端口取决于你的 Docker 配置）
BETTERDB_TOKEN	—	在 Settings → MCP Tokens 中获取的 MCP 令牌。云端必需。可自托管环境中可选：不提供时，读取工具可匿名使用；提供后，调用将以令牌所有者的身份执行（写入工具需要管理员的令牌），所做更改会在活动日志中记录为该所有者所为。令牌无法管理成员或其他令牌
BETTERDB_INSTANCE_ID	—	预先选择特定实例（跳过 select_instance）

CLI 参数

参数	默认值	描述
--autostart	—	启动时启动并管理本地 BetterDB 监控进程
--persist	—	MCP 服务退出后仍保持监控进程运行（需要 --autostart）
--port <number>	3001	自动启动的监控 API 端口
--storage <type>	sqlite	存储后端：sqlite 或 memory
--stop	—	停止之前持久运行的监控进程并退出

可用工具

实例工具

工具	描述
list_instances	列出所有已注册且包含连接状态的 Valkey/Redis 实例
select_instance	选择后续调用所操作的实例
get_health	综合健康状况摘要——任何问题排查的最佳起点
get_info	完整的 INFO 统计信息，可按部分筛选
get_slowlog	慢日志缓冲区中的近期慢命令
get_commandlog	近期 COMMANDLOG 条目（Valkey 8+）
get_latency	延迟事件历史记录
get_latency_history	特定延迟事件的详细历史记录
get_memory	MEMORY DOCTOR 评估和 MEMORY STATS 明细
get_clients	活跃客户端列表及连接详情
get_hot_keys	来自 LFU 或空闲时间分析的热点键跟踪数据
get_slowlog_patterns	汇总后的慢日志模式，包含频率和平均耗时
get_commandlog_history	持久化的 COMMANDLOG 条目，可按时间范围筛选
get_commandlog_patterns	汇总后的 COMMANDLOG 模式
get_anomalies	异常检测事件 (Pro)
get_client_activity	根据持久化快照按时间段统计的客户端活动
get_acl_audit	ACL 审计日志条目
get_cluster_nodes	集群节点发现——角色、健康状况、槽位范围
get_cluster_node_stats	集群中每个节点的性能统计信息
get_cluster_slowlog	汇总所有集群节点的慢日志
get_slot_stats	每个槽位的键数量和 CPU 使用率（Valkey 8+）

分析工具

工具	描述
get_forecast	指标（opsPerSec、usedMemory、cpuTotal、memFragmentation）的容量预测，并预估达到上限的时间
get_latency_regressions	根据异常存储检测相对于基线持续出现的 p99 延迟退化 (Pro)
get_largest_keys	根据键分析快照，按测得的内存使用量列出最大的键 (Pro)

向量搜索工具

适用于运行 Search 模块（valkey-search / RediSearch）的部署。

工具	描述
get_vector_indexes	每个索引的健康状况：文档数量、内存使用量、索引失败次数和已索引百分比
get_inference_latency	每个向量索引的 FT.SEARCH p50/p95/p99 以及 SLA 违约状态（SLA 字段需要 Pro）

AI 可观测性工具

适用于 AI 组件（语义缓存、Agent 缓存、Agent 记忆存储、检索流水线）以及通过 OpenTelemetry 摄取的跟踪数据。

工具	描述
ai_list_instances	查看所有 AI 组件实例的综合发现视图，包含存活状态和最新指标样本
ai_instance_history	单个 AI 组件实例的已存储指标时间序列（命中率、节省的成本、驱逐次数、阈值等）
list_ai_traces	列出近期 AI 应用跟踪数据（大模型调用、缓存查询、记忆召回、检索跨度）
get_ai_trace	单个跟踪的完整跨度瀑布图，包含耗时、父子关系和属性
correlate_ai_trace	将跟踪中的缓存／记忆跨度与实时 Valkey 状态关联，以解释未命中或过时的召回

连接管理工具

工具	描述
add_connection	向 BetterDB 添加新的 Valkey／Redis 连接
test_connection	测试连接凭据，但不保存
remove_connection	从 BetterDB 移除连接
set_default_connection	将某个连接设为当前默认连接

监控生命周期工具

工具	描述
start_monitor	启动持久运行的 BetterDB 后台监控进程
stop_monitor	停止先前启动的持久监控进程

缓存智能工具

适用于运行 @betterdb/semantic-cache 或 @betterdb/agent-cache 的部署。缓存会在 Valkey 端的发现哈希中注册自身；Monitor 通过以下工具提供这些缓存的信息。

只读：

工具	描述
cache_list	列出当前实例注册的所有缓存，以及命中率和总操作数
cache_health	查看单个缓存的详细健康状况；响应字段根据 cache_type（semantic_cache 或 agent_cache）区分
cache_threshold_recommendation	根据滚动相似度窗口，为 semantic_cache 提供阈值调整建议
cache_tool_effectiveness	提供 agent_cache 各工具的命中率、节省的成本和 TTL 建议
cache_similarity_distribution	查看 semantic_cache 近期相似度分数的直方图（20 个分桶，宽度为 0.1）
cache_recent_changes	查看单个缓存的近期提案（任何状态），以便 Agent 避免重复提案

提议更改（仅提供建议 — 批准前不会写入 Valkey）：

工具	描述
cache_propose_threshold_adjust	提议更改 semantic_cache 的相似度阈值（按类别或全局）
cache_propose_tool_ttl_adjust	提议更改 agent_cache 中某个工具的 TTL
cache_propose_invalidate	提议执行失效操作；筛选条件结构根据缓存类型区分

批准／拒绝／列出：

工具	描述
cache_list_pending_proposals	列出当前实例的待处理提案，可按 cache_name 筛选
cache_get_proposal	按 id 获取单个提案，包含其审计记录
cache_approve_proposal	批准待处理提案；同步将更改应用到 Valkey
cache_reject_proposal	拒绝待处理提案，可附带原因
cache_edit_and_approve_proposal	编辑提案的值（阈值或 TTL）并一步批准；失效提案不可编辑

要求

• Node.js 20+
• 正在运行的 BetterDB 实例（云端或可自托管），也可使用 --autostart 让 MCP 服务自动管理实例

文档

完整文档：docs.betterdb.com

许可证

详情请参阅 LICENSE。