Betterdb Mcp

@betterdb/mcp

AI アシスタントから、Valkey および Redis データベースを詳細に把握できます。BetterDB MCP サーバーは、Claude Code、Cursor、Windsurf、その他のMCP互換クライアントをBetterDB監視プラットフォームに接続します。エディターを離れることなく、AI がリアルタイムのメトリクスを照会し、遅いコマンドを診断し、異常を検出し、インシデントを調査できるようになります。

BetterDB Monitor で実際の動作を見る

BetterDB Monitorでは、Valkey 上で実行されている AI ワークロードのライブダッシュボードを確認できます。

• AI Cache & Memory - すべてのキャッシュとメモリストアのヒット率、削減コスト、エビクション、インデックスサイズとその履歴を確認できます。
• AI Traces - リクエストごとの OpenTelemetry ウォーターフォールをライブの Valkey 状態と関連付け、各キャッシュヒットとミスの理由を把握できます。

セルフホストで実行する（docker run -p 3001:3001 betterdb/monitor）か、BetterDB Cloudを利用してください。Search モジュールを含む、管理された TLS 対応の Valkey インスタンスもワンクリックでプロビジョニングできます。

BetterDB を選ぶ理由

BetterDB は Valkey と Redis 向けに構築された監視・オブザーバビリティプラットフォームで、Valkey および Redis のデプロイメント向けにリアルタイムダッシュボード、異常検知、運用インテリジェンスを提供します。ライブスナップショットしか表示しないツールとは異なり、BetterDB は過去のメトリクス、スローログ、監査証跡を保持するため、現在の状況だけでなく、昨日何が起きたかも調査できます。

MCP を通じて利用できる主な機能：

• リアルタイムのヘルスチェック — メモリの断片化、ヒット率、レプリケーションの遅延、接続中のクライアント
• 低速コマンドの分析 — パターン集計を含むスローログと COMMANDLOG（Valkey 8 以降）
• ホットキーの検出 — LFU 頻度スコアまたはアイドル時間の分析によって、キャッシュを無効化するキーを特定
• クラスター全体の可視性 — 全ノードのノードごとの統計、集計されたスローログ、スロット単位のメトリクス
• 異常検知 — メモリ、CPU、ヒット率などのメトリクスに対する Z スコア分析（Pro）
• クライアントアクティビティの追跡 — 接続数、コマンドの分布、バッファ使用量の推移
• ACL 監査ログ — 認証失敗とアクセスパターンを調査
• レイテンシイベントの履歴 — 特定のイベントタイプのレイテンシ傾向を追跡

クイックスタート

1. トークンを取得する

BetterDB で、Settings → MCP Tokens に移動し、新しいトークンを生成します。

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 インスタンスの状態はどうですか？」
• 「過去 1 時間で最も遅かったコマンドを表示してください」
• 「負荷の偏りを引き起こしているホットキーはありますか？」
• 「メモリ使用量が最も多いクラスターノードはどれですか？」
• 「過去 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	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	頻度と平均所要時間を含む、集計済みの slowlog パターンを取得します
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	すべてのクラスターノードの 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 オブザーバビリティツール

OpenTelemetry 経由で取り込まれた AI コンポーネント（セマンティックキャッシュ、エージェントキャッシュ、エージェントメモリストア、検索パイプライン）およびトレースを対象とします。

ツール	説明
ai_list_instances	稼働状況と最新のメトリクスサンプルを含む、すべての AI コンポーネントインスタンスの統合検出ビュー
ai_instance_history	1 つの AI コンポーネントインスタンスの保存済みメトリクス時系列（ヒット率、削減コスト、エビクション、しきい値など）
list_ai_traces	最近の AI アプリケーショントレースを一覧表示（LLM 呼び出し、キャッシュ検索、メモリ想起、検索スパン）
get_ai_trace	1 つのトレースのスパン全体をウォーターフォール形式で表示。タイミング、親子関係、属性を含みます
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	1 つのキャッシュの詳細なヘルス情報を表示します。応答の分岐は 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	1 つのキャッシュに対する最近の提案（ステータスを問わず）を表示し、エージェントが同じ提案を繰り返さないようにします

変更の提案（アドバイザリー — 承認されるまで 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）を編集して、1 回の操作で承認します。無効化の提案は編集できません

要件

• Node.js 20 以降
• 稼働中の BetterDB インスタンス（クラウドまたはセルフホスト可能）。または --autostart を使用して、MCP サーバーに自動管理させます

ドキュメント

ドキュメント全文：docs.betterdb.com

ライセンス

詳細は LICENSE を参照してください。