Redis MCP: AIエージェントをデータベースに接続する

Redis MCPを使用すると、AIクライアントはRedisデータベースのデータを読み書きするツールを呼び出せます。独自のデータベースに接続するには、公式のredis-mcp-serverを実行し、Redisのアドレスと制限付きの認証情報を指定して、そのプロセスをCursorまたはClaude Desktopに登録します。

このガイドでは、2つの小さなデモ用キーを使用して接続を機能させます。文字列とハッシュを読み取り、TTLを確認し、Redisが書き込みを拒否することをチェックします。まずは自分のコンピュータで開始し、その後Lizardの専用Managed Redisインスタンスでも同じアプローチを使用できます。

テスト実施日 2026年9月27日（ドバイ時間）: Python 3.12.10、Redis 8.8.0、redis-mcp-server 0.5.1、MCP Python SDK 1.30.0、およびredis-py 8.1.0。ダウンロード可能なテストは、stdio経由のMCPを介して、分離されたローカルのRedisプロセスに対する14のチェックに合格しました。ホスト型データベース、TLS、またはCursorやClaude Desktopのインターフェースはテストしていません。これらの設定手順は、リンク先の製品ドキュメントに従います。このガイドはAIの支援を受けて作成されました。テストスクリプトと結果は以下で利用可能です。

データにアクセスするRedis MCPサーバーを選択する

公式のRedis MCPサーバーはRedisエンドポイントに接続します。そのツールには、文字列とハッシュの読み取り、書き込み、キーの検査、サーバー情報が含まれます。Redisは、提供された認証情報の権限を適用します。

名前にMCPが含まれるRedisツールはいくつかあります。

ここでは最初のものを使用します。ドキュメントへの接続では、エージェントにキーへのアクセス権は付与されません。Redisはエージェント設定ガイドでその違いを説明しています。

MCPプロセスはクライアントと同じコンピュータ上で実行され、標準入出力（stdio）を通じて通信します。そして、Redisへの個別のネットワーク接続を開きます。この設定では、MCP用のパブリックなHTTPエンドポイントは必要ありません。クライアントの緑色の接続インジケーターは、MCPプロセスが開始されたことのみを示します。Redisの認証とデータアクセスが機能することは、ツール呼び出しによって証明する必要があります。

1. 小規模なRedisデータベースを準備する

合成データを含む専用の学習用インスタンスを使用します。Python 3.10以降、uv、およびRedisサーバーへのアクセスが必要です。ローカル環境の場合は、PATHにredis-serverも必要です。

以下のファイルを新しいデモ用ディレクトリにダウンロードします。

• requirements.txt: バージョン固定されたPythonパッケージ。
• setup.py: 2つのキーと読み取り専用ユーザーを作成し、MCP設定を書き込みます。
• verify.py: 独自のローカルRedisプロセスを起動し、MCP接続をテストします。
• validation.json: このガイドのテスト実行結果。

macOSまたはLinuxの場合、Python環境を作成します。

uv venv .venv --python 3.12
uv pip install --python .venv/bin/python -r requirements.txt

別のターミナルで、一時的なRedisインスタンスを起動します。

redis-server --bind 127.0.0.1 --port 6391 --save "" --appendonly no

そのターミナルは実行したままにします。このローカルインスタンスには永続性がなく、ループバックでのみリッスンします。終了したらCtrl+Cで停止してください。ポート6391がすでに別のプロセスで使用されている場合は、空いているポートを選び、セットアップを実行する前にADMIN_REDIS_URLを合わせて設定してください。

デモ用ディレクトリで以下を実行します。

.venv/bin/python setup.py

セットアップスクリプトはデフォルトでredis://127.0.0.1:6391/0に接続します。以下を作成します。

また、ランダムなパスワードを持つユーザーmcp_readerも作成します。既存のユーザーやデモ用キーの上書きは拒否するため、同じインスタンスで繰り返し実行すると説明メッセージとともに停止します。

スクリプトは、インストールされたMCPサーバーへの絶対パスを含むmcp.local.jsonを保存します。このファイルには読み取り専用ユーザーのパスワードが含まれています。非公開に保ち、コミットする前にデモプロジェクトの.gitignoreに以下のパスを追加してください。

.venv/
.env
mcp.local.json
.cursor/mcp.json
test-runs/

Windowsの場合、Pythonコマンドには.venv\Scripts\python.exeを使用します。スクリプトは、生成される設定に一致する実行可能ファイルのパスを選択します。このガイドの自動実行ではmacOSを使用しました。

2. 読み取り専用ユーザーの権限を理解する

スクリプトは以下のRedis ACLポリシーを適用します。これはRedisコマンドの構文であり、パスワードはプレースホルダーです。セットアップスクリプトが実際のパスワードを生成します。

ACL SETUSER mcp_reader reset on >REPLACE_WITH_RANDOM_PASSWORD ~mcpdemo:* -@all +ping +get +hget +hgetall +type +ttl

このルールは、mcpdemo:*配下の既知の文字列とハッシュの読み取り、およびタイプとTTLのチェックを許可します。書き込み、管理コマンド、pub/sub、およびキーの列挙は拒否します。Redis ACLリファレンスで各ルールが説明されています。

読み取り専用のプロンプトは、読み取り専用アクセスを強制しません。 データベースの認証情報がそれを強制します。MCPサーバーは依然として書き込みツールを提示できますが、Redisはこのユーザーに対するその実行を拒否するはずです。どの呼び出しが実行されるかを確認する別の手段として、クライアントの承認プロンプトを有効にしたままにしてください。

ポリシーがSCANを許可しない理由

ACLのキーパターンは、キーの値へのアクセスを制限します。SCANがそのパターンのキー名のみを返すようにするわけではありません。私たちのテストでは、+scanを付与すると、mcp_readerはそのキーの値を読み取れないにもかかわらず、private:sentinelという名前を発見できました。SCANを取り消すと、列挙は再びブロックされました。

既知のデモ用キーから始めてください。後で無関係なデータを持たない別のインスタンスでブラウジングを許可する場合は、scan_keysを小さな反復で使用し、返されるカーソルがゼロになるまで追跡します。COUNTは作業のヒントであり、厳密な結果の制限ではありません。SCANリファレンスを参照してください。このチュートリアルのデフォルトポリシーは、意図的にscan_keysとscan_all_keysの両方を拒否します。

3. CursorまたはClaude DesktopにRedis MCPを追加する

生成されたmcp.local.jsonをローカルで開きます。以下のような形式です。

{
  "mcpServers": {
    "redis-demo": {
      "command": "/ABSOLUTE/PATH/redis-mcp-demo/.venv/bin/redis-mcp-server",
      "args": ["--host", "127.0.0.1", "--port", "6391", "--db", "0"],
      "env": {
        "REDIS_USERNAME": "mcp_reader",
        "REDIS_PWD": "YOUR_GENERATED_READER_PASSWORD"
      }
    }
  }
}

上記のプレースホルダーではなく、実際に生成されたファイルを使用してください。redis-demoエントリをクライアントの既存のmcpServersオブジェクトにマージします。すでに存在する他のサーバーはそのまま保持します。

Cursor: デモプロジェクトでは.cursor/mcp.jsonを使用するか、ユーザーレベルの設定では~/.cursor/mcp.jsonを使用します。クライアントのMCP設定でサーバーを確認し、プロジェクトに対して有効にします。CursorはMCP統合ガイドでファイルの場所を文書化しています。

Claude Desktop: エントリをclaude_desktop_config.jsonにマージします。macOSでは、このファイルは~/Library/Application Support/Claude/の下にあります。保存後、アプリを再起動します。現在のクライアントの手順については、Redisクライアント設定ガイドに従ってください。

このガイドでは、ホスト、ポート、データベースを明示的な引数として渡します。テストした0.5.1のコマンドラインエントリポイントでは、環境変数のみを指定した場合、デフォルトのCLI値がそれらの設定を上書きします。したがって、REDIS_HOSTのみを指定すると、プロセスが127.0.0.1を試行したままになる可能性があります。上記の設定のユーザー名とパスワードは、サポートされているREDIS_USERNAMEおよびREDIS_PWD変数を使用しています。

4. 接続を確認する

クライアントにRedisツールを明示的に使用するように依頼します。モデルの要約に頼る前に、要求された読み取りを承認し、ツールの出力を確認してください。

Use redis-demo to get mcpdemo:status. Then use hgetall on
mcpdemo:session:42 and type on that same key. Report the raw
tool results and the remaining TTL. Do not change any data.

期待される結果は以下の通りです。

• getはreadyを返します。
• hgetallは2つの合成フィールドを返します。
• typeはhashと、3,600秒未満の正のTTLを返します。

公式のtypeツールは、レスポンスにTTLを含みます。私たちの実行では以下を返しました。

{
  "key": "mcpdemo:session:42",
  "type": "hash",
  "ttl": 3591
}

あなたの数値は異なります。TTLが-2の場合はキーが存在しないことを意味し、-1の場合は有効期限なしで存在することを意味します。1時間以上経過している場合、デモデータは期限切れになっている可能性があります。承認された管理者がキーを再生成するか、新しいローカルインスタンスを起動してセットアップを再実行できます。

次に、使い捨てのデモを使用して制限をチェックします。

Use redis-demo to try setting mcpdemo:status to changed once.
Report the exact tool result. Then read mcpdemo:status again.
Do not retry with other tools or credentials.

私たちのMCP呼び出しはUser mcp_reader has no permissions to run the 'set' commandを返し、別の読み取りでは依然としてreadyが返されました。これにより、拒否されたことと値が変更されていないことの両方が検証されます。一部のRedis MCPツールはエラーをテキストとして返すため、MCP呼び出し自体が完了した場合でもレスポンスの内容を確認してください。

モデルのAPIキーがなくても、基盤となるプロトコルチェックを再現できます。

.venv/bin/python verify.py

スクリプトは、空いているループバックポートで独自のRedisプロセスを起動します。データベースのURLは受け付けません。認証、MCPの起動、提示されたツール、読み取り、TTL、ブロックされた書き込み、変更されていないデータ、別のキープレフィックス、欠落しているキー、および上記のSCANの動作をチェックします。作成したプロセスのみを停止し、スクリプトの横にvalidation.jsonを保存します。

5. 専用のManaged Redisインスタンスを接続する

共有アプリケーションデータベースの場合は、プロジェクトダッシュボードでManaged Redisを作成し、接続ガイドに従ってください。この演習には別の学習用インスタンスを使用します。その接続URLを、ADMIN_REDIS_URLという名前で非公開のローカル.envファイルにコピーします。その管理者認証情報をAIチャットに貼り付けないでください。

信頼できる自身のファイルを読み込み、デモ用ディレクトリからセットアップを実行します。

set -a
. ./.env
set +a
.venv/bin/python setup.py
unset ADMIN_REDIS_URL

セットアップスクリプトは、その認証情報を使用して合成キーと読み取り専用ユーザーを作成します。生成されたMCP設定には、新しい読み取り専用ユーザーの認証情報のみが含まれます。URLからホスト、ポート、データベースを抽出し、rediss://エンドポイント用に証明書の検証を有効にしたTLSオプションを追加します。クエリパラメータやカスタム証明書のパスには個別の設定が必要です。スクリプトはそれらを推測するのではなく停止します。

エンドポイントは、MCPを実行しているコンピュータから到達可能である必要があります。プレーンなredis:// URLにはトランスポート暗号化がありません。可能な場合は、信頼できるプライベートルートまたは検証済みのTLSエンドポイントを使用してください。URLプレフィックスを変更しても、サーバーにTLSサポートが追加されるわけではありません。現在のManaged Redisガイドはredis://接続を示しているため、パブリックなTLSエンドポイントが提供されると想定しないでください。

ACLユーザーを作成するには、プロバイダーがACL SETUSERを許可している必要もあります。プロバイダーがそれを拒否する場合は、エージェントを接続する前に、サポートされているユーザー管理コントロールを使用してください。回避策として管理者パスワードをMCP設定に入れないでください。

実行時に行われたRedis ACLの変更がRedisの再起動後も存続するには、永続化メカニズムが必要です。現在のManaged Redisの起動設定ではACLファイルが宣言されていないため、このデモユーザーは一時的なものとして扱い、再起動後に確認してください。AOFの永続化がACLユーザーを保存すると想定しないでください。テスト済みの権限をセットアッププロセスに保持し、サービスのその他の制限についてはストレージとリカバリのガイドを確認してください。

よくあるRedis MCP接続エラーを修正する

接続が機能した後に構築するもの

この設定を使用して、合成セッションを検査したり、キャッシュエントリの有効期間を確認したり、エージェントの保存されたコンテキストをデバッグしたりします。ツールの結果はモデルの会話に入る可能性があるため、実際のアプリケーションを接続する前に、エージェントが読み取ってもよいデータを選択してください。

アプリケーションにメモリを自動的に保存させたい場合は、Redisを使用したAIエージェントメモリに進んでください。エージェントにリレーショナルデータが必要な場合は、Postgres MCPの個別の読み取り専用ロールを使用してください。

Managed Redisから始め、読み取り専用ユーザーを接続し、ツールセットを拡張する前に、1回の成功した読み取りと1回の拒否された書き込みを検証してください。