Redis MCPサーバーの使い方 — キー操作からPub/Subまで

Redis公式のMCPサーバー(redis-mcp-server)を使うと、ClaudeとのチャットからそのままRedisを操作できます。対象は文字列・ハッシュ・リスト・セット・ソート済みセット・Pub/Sub・ストリーム・JSONドキュメントです。MITライセンスで、Redis社が自社アカウントで開発と保守をしています。この記事ではClaude DesktopとClaude Codeそれぞれへの接続手順、接続文字列、ACLで書き込みを止める方法、インストール方法の使い分けをまとめます。

Redis MCPサーバーで何ができるか

このMCPサーバーは、Redisのデータ型ごとに操作ツールを持っています。ツール名はソースのsrc/toolsに並ぶ関数名で、Redisのコマンド名に近い命名です。

ツール

データ型ごとのツール

string / hash
set(有効期限付き)・get、hset・hget・hgetall・hdel・hexists。ハッシュにはベクトル埋め込みを格納するset_vector_in_hash・get_vector_from_hashもあります。
list / set / sorted set
lpush・rpush・lpop・rpop・lrange・llen・lrem、sadd・srem・smembers、zadd・zrange・zrem。キュー、重複のない集合、ランキングに使えます。
pub/sub と streams
publish・subscribe・psubscribe・read_messages・unsubscribe。購読は状態を持ち、返ってくる購読IDでread_messagesを呼んでたまったメッセージを読みます。ストリームはxadd・xrange・xdel・xgroup_create・xgroup_destroy・xreadgroup・xackなどです。
JSON と query engine
json_set・json_get・json_delはパスを指定してネストしたデータを更新します。create_vector_index_hash・vector_search_hash・hybrid_searchなどは、ハッシュに入れたベクトルの類似検索やRAG(検索拡張生成)用のインデックスを扱います。インデックスの確認にはget_indexes・get_index_info・get_indexed_keys_numberがあります。
キー管理とサーバー情報
delete・type・expire・rename・scan_keys・scan_all_keys、サーバー側はdbsize・info・client_listです。

もう一つ、Redisの公式ドキュメントを自然言語で検索するsearch_redis_documentsツールがあります。検索先はMCP_DOCS_SEARCH_URL環境変数で変えられ、ソースの既定値はhttps://redis.io/convai/api/docs/searchです。この変数を自前の検索APIに向けることもできます。その場合、サーバーのソースは?q=<質問>のGETリクエストを送ります。

対応する接続方式はstdioのみです。READMEにはstreamable-httpトランスポートを将来追加すると書かれていて、リモートのHTTPエンドポイントとして公開する用途にはまだ使えません。ローカルプロセスとして起動する前提です。

Entra ID認証を使う場合

Azure Managed Redisを使っているなら、パスワード認証の代わりにEntra ID(旧Azure Active Directory)でMCPサーバーを認証できます。この認証はAzure Managed Redis向けの機能なので、対象外なら次の節へ進んで構いません。認証フローはREDIS_ENTRAID_AUTH_FLOWにフロー名を入れて有効にし、3種類から選びます。

フロー(値)	用途	設定する環境変数
`service_principal`	用途アプリケーション単位の認証	設定する環境変数`REDIS_ENTRAID_CLIENT_ID` / `REDIS_ENTRAID_CLIENT_SECRET` / `REDIS_ENTRAID_TENANT_ID`
`managed_identity`	用途Azure上で動くアプリからの認証	設定する環境変数`REDIS_ENTRAID_IDENTITY_TYPE`(`system_assigned`が既定。`user_assigned`なら`REDIS_ENTRAID_USER_ASSIGNED_CLIENT_ID`も)
`default_credential`	用途ローカル開発(Azure CLIログイン済み)	設定する環境変数`REDIS_ENTRAID_SCOPES`(既定値は`https://redis.azure.com/.default`で、通常は省略できる)

トークンの更新はバックグラウンドで自動的に行われ、フローを指定しなければ通常のパスワード認証のままです。ローカル開発なら、az login済みの状態でREDIS_ENTRAID_AUTH_FLOW=default_credentialと接続先のREDIS_URLを指定するのが最短です。

Claude Desktopへの接続手順

手順

Claude Desktopに接続する流れ

1
uvxのフルパスを調べる
ターミナルでwhich uvxを実行し、表示されたパスを控えます。Claude Desktopが起動する環境ではuvxが見つからないことがあるため、commandにはこのフルパスを書きます。
2
claude_desktop_config.jsonに追記する
mcpServersに下のブロックを足します。--urlのあとに接続先を渡します。
3
Claude Desktopを再起動する
設定画面のMCPサーバー一覧にredis-mcp-serverが出れば接続できています。
4
動かなければログを見る
後述のtailでログを追うと、起動時のエラーが読めます。

推奨インストール方法はPyPIパッケージをuvxで実行する形です。uvxはパッケージを一時環境にダウンロードして実行するツールで、事前のpipインストールが要りません。

{
  "mcpServers": {
    "redis-mcp-server": {
      "type": "stdio",
      "command": "/Users/you/.local/bin/uvx",
      "args": [
        "--from", "redis-mcp-server@latest",
        "redis-mcp-server",
        "--url", "redis://localhost:6379/0"
      ]
    }
  }
}

READMEのサンプルは"command": "uvx"と書いてあり、そのまま貼ると「コマンドが見つからない」エラーになることがあります。手順1で調べたフルパスに置き換えてください。

tail -f ~/Library/Logs/Claude/mcp*.log

Claude Codeへの追加コマンド

Claude Codeでは設定ファイルを手で書かずに、claude mcp addコマンドで追加できます。ローカルプロセスとして起動するstdioサーバーは、Claude Code独自のオプションとサーバーへ渡す引数を--で区切ります。

claude mcp add --transport stdio redis \
  -- uvx --from redis-mcp-server@latest redis-mcp-server \
  --url redis://localhost:6379/0

環境変数で接続情報を渡したい場合は、--env(短縮形-e)をサーバー名の前に置きます。v2.1.289のclaude mcp add --helpでは-e, --env <env...>と複数値を取る形で表示されます。--envの直後にサーバー名を書くと、名前まで環境変数の値として読まれて弾かれるため、間に--transportなどを挟みます。

claude mcp add --env REDIS_PWD=mypassword --transport stdio redis \
  -- uvx --from redis-mcp-server@latest redis-mcp-server --host localhost

Claude Code自体のMCP設定の構文やスコープ(ローカル・プロジェクト・ユーザー)はClaude Code MCP設定ガイドで扱っています。MCPプロトコル自体の仕組みから確認したい場合はMCPとはが背景を説明しています。

接続文字列と書き込みを止めるACL

接続先は--url引数か個別の--host --port --password引数で指定します。URLの形式はredis://user:secret@host:port/dbで、暗号化接続が必要な場合はrediss://スキームを使います。

# 平文接続(ローカル開発向け)
redis://localhost:6379/0
 
# 暗号化接続(Redis Cloud等)
rediss://user:secret@host:6379/0?ssl_cert_reqs=required&ssl_ca_certs=/path/to/cert

設定の優先順位は、コマンドライン引数、環境変数、既定値の順です。--hostも--urlも渡さなければ127.0.0.1:6379。

Claudeに本番のRedisを触らせるなら、書き込みをRedis側で止めておくと安全です。READMEにある読み取り専用ユーザーの作り方は次のとおりです。

# Redis CLI上でACLを設定する例
127.0.0.1:6379> ACL SETUSER readonlyuser on >mypassword ~* +@read -@write

このユーザーで接続したとき、各ツールが内部で呼ぶコマンドは、Redis 6.0.9のインスタンスでは次のように振り分けられます。

くらべる

readonlyuserで通るツールと拒否されるツール

読み取り系

通る

get(GET)、type、scan_keys・scan_all_keys(SCAN)、hgetall、lrange、dbsize、xrange。値の取得や走査はそのまま返ります。

書き込み・管理系

拒否される

set、delete(DEL)、expire、renameはNOPERMで失敗します。publish・subscribe・xreadgroup・info・client_listも、+@readの範囲に入らないため同じく拒否されました。

拒否されたときのエラーは「this user has no permissions to run the 'set' command」の形です。infoとclient_listまで止まる点は見落としやすく、サーバー情報をClaudeに見せたいなら、+infoのようにコマンド単位で許可を足します。ACLの文法そのものはRedisのACLドキュメントが詳しく、コマンドのカテゴリはRedisのバージョンで増減するため、使う環境のACL CATで確かめておくと確実です。

作成したユーザーの認証情報は--username --password(またはURLのuser:secret部分)で渡します。Redis Cluster構成のデータベースへつなぐ場合は、--cluster-mode(または環境変数REDIS_CLUSTER_MODE)を有効にします。このフラグを付けるとredis-pyのクラスター用クライアントで接続するため、クラスター構成のデータベースでは付けておきます。

インストール方法の使い分け

インストール方法は4通りあり、用途によって向き不向きが分かれます。

方法	向いている場面	注意点
PyPI(`uvx`)	向いている場面個人利用・すぐ試したい場合	注意点`redis-mcp-server@latest`は起動のたびに最新版を確認する
GitHubからのタグ指定	向いている場面バージョンを固定したい場合	注意点`main`ブランチは開発中で破壊的変更が入りうる、タグ指定を推奨
ソースクローン	向いている場面サーバー自体を改造・デバッグする場合	注意点`uv sync`で依存関係を入れ、`src/main.py`を直接実行
Docker	向いている場面コンテナ環境に統合する場合	注意点公式イメージ`mcp/redis`をDocker Hubで配布

PyPI経由でもredis-mcp-server@latestの代わりにバージョン番号を直接指定すれば、uvxのまま特定バージョンに固定できます。PyPIの0.5.1は2026年8月5日に公開されたバージョンです。GitHubのタグを指定する場合は次のように書きます。

uvx --from git+https://github.com/redis/mcp-redis.git@0.5.1 \
  redis-mcp-server --url redis://localhost:6379/0

Dockerで動かす場合は、リポジトリのDockerfileでイメージをビルドするか、公式イメージmcp/redisを指定します。次の例は公式イメージを使う形です。

{
  "mcpServers": {
    "redis": {
      "command": "docker",
      "args": ["run", "--rm", "--name", "redis-mcp-server", "-i",
        "-e", "REDIS_HOST=<redis_hostname>",
        "-e", "REDIS_PORT=<redis_port>",
        "-e", "REDIS_PWD=<redis_password>",
        "mcp/redis"]
    }
  }
}

よくあるつまずき

接続先を指定し忘れる。--urlも--hostも渡さないと、既定値の127.0.0.1:6379へ接続を試みます。反応がないときは、まず接続先を明示したかを確認します。

ログが何も出ない。既定のログレベルはWARNING以上のみで、通常の起動メッセージは表示されません。動作確認中はMCP_REDIS_LOG_LEVEL=INFO(さらに詳しく見たいならDEBUG)を環境変数に足します。MCPクライアント側が既にログハンドラーを持っている場合、サーバーは独自のハンドラーを追加せず、設定したレベルが握りつぶされないようにしきい値だけを緩めます。ハンドラーが無い環境では標準エラー出力に書き出す仕組みです。

EntraID認証の変数を無関係な環境で設定してしまう。REDIS_ENTRAID_*系の変数はAzure Managed Redis向けの機能です。REDIS_ENTRAID_AUTH_FLOWを設定しなければ有効にならないので、使わない環境では触らなくて構いません。

動作確認にMCP Inspectorを使わない。設定ファイルを直接編集して動かないと原因の切り分けに時間がかかります。MCP Inspectorの使い方にあるように、npx @modelcontextprotocol/inspector uv run src/main.pyでツール単位の動作を先に確認すると早いです。

まとめ

個人利用ならPyPI経由のuvxが最短です。本番のRedisにつなぐ前に、読み取り専用ACLのユーザーを作って、infoなど必要なコマンドだけを足す構成から始めると、Claudeの操作範囲をRedis側で決められます。

最初の一歩は、ローカルのRedisをredis://localhost:6379/0でつないでsetとgetを試すところです。Redisをアプリケーションの永続化先として使う場合の実装はAgent SDK SessionStoreでセッションをS3やRedisに永続化するも参考になります。Redis Cloudのサブスクリプションやデータベースの作成まで任せたいときは、別のMCPサーバーを使うRedis Cloud MCPサーバーの記事があります。

Redis MCPサーバーの使い方 — キー操作からPub/Subまで

Redis MCPサーバーで何ができるか

Entra ID認証を使う場合

Claude Desktopへの接続手順

Claude Codeへの追加コマンド

接続文字列と書き込みを止めるACL

インストール方法の使い分け

よくあるつまずき

まとめ

MCPとは — AIと外部ツールをつなぐ標準プロトコルの仕組み・採用状況・Claudeでの使い方

Redis Cloud MCPサーバーでサブスクリプションを管理する

Unreal Engine 5.8のMCPをClaude Codeから使う設定ガイド

Twilio MCPサーバーの使い方 — 認証不要のAPI仕様検索をClaude Codeに接続する

TavilyのMCPサーバーをClaude Codeに接続する手順

Statsig MCPサーバーでフラグと実験をClaude Codeから操作する

Redis MCPサーバーで何ができるか

Entra ID認証を使う場合

Claude Desktopへの接続手順

Claude Codeへの追加コマンド

接続文字列と書き込みを止めるACL

インストール方法の使い分け

よくあるつまずき

まとめ

関連する記事

MCPとは — AIと外部ツールをつなぐ標準プロトコルの仕組み・採用状況・Claudeでの使い方

Redis Cloud MCPサーバーでサブスクリプションを管理する

Unreal Engine 5.8のMCPをClaude Codeから使う設定ガイド

Twilio MCPサーバーの使い方 — 認証不要のAPI仕様検索をClaude Codeに接続する

TavilyのMCPサーバーをClaude Codeに接続する手順

Statsig MCPサーバーでフラグと実験をClaude Codeから操作する