/ 目錄 / 演練場 / Redis
● 官方 redis 🔑 需要你的金鑰

Redis

作者 redis · redis/mcp-redis

用中文操作 Redis — 查看金鑰、管理快取、調整過期時間、除錯 pub/sub,不需要死背每條 Redis 指令。

Redis 官方 MCP 透過型別化工具完整暴露 Redis 指令介面:字串、雜湊、列表、集合、有序集合、串流、pub/sub 及金鑰管理。預設使用單一 Redis URL,相容 OSS Redis、Redis Stack、Redis Cloud 及 ElastiCache/MemoryDB。

為什麼要用

核心特性

即時演示

實際使用效果

redis.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "redis": {
      "command": "uvx",
      "args": [
        "mcp-redis"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "redis": {
      "command": "uvx",
      "args": [
        "mcp-redis"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "redis": {
      "command": "uvx",
      "args": [
        "mcp-redis"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "redis": {
      "command": "uvx",
      "args": [
        "mcp-redis"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "redis",
      "command": "uvx",
      "args": [
        "mcp-redis"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "redis": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-redis"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add redis -- uvx mcp-redis

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: Redis

排查快取值過期或遺失的原因

👤 排查快取問題的後端工程師 ⏱ ~10 min beginner

何時使用: 使用者反映「我更新了個人資料,但頁面仍顯示舊名稱」— 很可能是快取失效問題。

前置條件
  • 具備至少讀取權限的 Redis URLREDIS_URL=redis://:pw@host:6379/0
步驟
  1. 找到對應的金鑰
    掃描符合 user:profile:42* 的金鑰,並列出每個金鑰的型別與 TTL。✓ 已複製
    → 符合條件的金鑰清單
  2. 檢查儲存的值與到期時間
    user:profile:42 執行 GET 取得值,並顯示 TTL。是否與預期不符?✓ 已複製
    → 值 + TTL + 判斷結果
  3. 主動刪除金鑰
    刪除該金鑰(及相關的 list/set 金鑰),讓應用程式在下次讀取時重新填充。確認刪除成功。✓ 已複製
    → DEL 回傳 1 或更多

結果: 確認快取已修復,並留有過期原因的完整紀錄。

注意事項
  • 在大型實例上執行 KEYS * 會造成伺服器阻塞 — 務必使用 SCAN(伺服器會將 scan 工具轉換為非阻塞的游標方式);永遠不要用 KEYS

稽核速率限制計數器以發現濫用模式

👤 平台/濫用防護團隊 ⏱ ~15 min intermediate

何時使用: 懷疑某客戶端正在突破速率限制;需要查看即時計數器與 TTL。

步驟
  1. 列出活躍的計數器
    掃描符合 ratelimit:* 的金鑰,依前綴分組,顯示每組的數量。✓ 已複製
    → 前綴分布統計
  2. 找出使用量最高的來源
    針對 ratelimit:api:*,回傳整數值最大的前 20 個金鑰。✓ 已複製
    → 前 20 個濫用來源
  3. 封鎖或重置
    對濫用金鑰 ratelimit:api:client_abc 執行 DELETE,讓下一次請求失敗放行;同時將 client_abc 加入封鎖名單集合 abuse:blocked,並設定 EXPIRE 86400。✓ 已複製
    → 金鑰已刪除 + 封鎖名單已更新

結果: 取得濫用的即時證據,並透過少量 Redis 操作完成精準封鎖。

注意事項
  • 刪除速率限制金鑰會讓客戶端立即再次突發請求 — 先將其加入封鎖名單集合,再刪除計數器 — 順序不能顛倒
搭配使用: sentry

找出並清除佔用記憶體的孤立 Session 金鑰

👤 回應 Redis 記憶體警報的 SRE ⏱ ~20 min intermediate

何時使用: Redis 已達 maxmemory 的 85%,需要在重要金鑰被驅逐前找出佔用記憶體的來源。

步驟
  1. 取樣大型金鑰
    透過 SCAN 取樣,並對每個金鑰使用 MEMORY USAGE,找出記憶體佔用最大的 50 個金鑰。✓ 已複製
    → 最大金鑰清單及其大小
  2. 依前綴分組並加總
    從取樣結果中,依冒號前的第一段分組,加總每組大小,找出佔用最多的前綴。✓ 已複製
    → 前綴 → 總位元組數
  3. 設定 TTL 修復問題
    對沒有 TTL(永久有效)的 session: 前綴金鑰,設定 EXPIRE 為 86400 秒。統計共更新了幾個金鑰。✓ 已複製
    → 已設定 TTL 的金鑰數量

結果: 釋放記憶體壓力,同時找到根本原因(session 寫入時未設定 EXPIRE),供應用程式修復。

注意事項
  • 在大型 hash/zset 上執行 MEMORY USAGE 代價高昂 — 透過 SCAN 取樣 5,000 至 10,000 個金鑰即可,不要掃描全部金鑰空間
搭配使用: sentry

檢查 Redis Stream 中卡住的消費者群組訊息

👤 使用 Redis Streams 作為工作佇列的工程師 ⏱ ~20 min advanced

何時使用: 消費者群組出現延遲;訊息未被 ack;吞吐量大幅下降。

步驟
  1. 檢查串流與群組狀態
    針對串流 jobs,顯示 XLEN、消費者群組及每個群組的待處理數量。✓ 已複製
    → 積壓數量
  2. 查看待處理的訊息
    針對群組 workers,列出前 20 筆 PEL 項目(XPENDING)— 顯示閒置時間與對應的消費者。✓ 已複製
    → 卡住的訊息 ID
  3. 重新認領或丟棄
    將閒置超過 300000 毫秒的訊息 XCLAIM 給新的消費者;若可以安全丟棄則執行 XACK。請先與我確認再執行。✓ 已複製
    → 重新認領/ack 摘要

結果: 串流恢復暢通,並留有每批訊息的處理決策紀錄(認領或 ack)。

注意事項
  • 未檢查訊息內容就 XACK 可能靜默丟失工作 — 務必先用 XRANGE 取得訊息內容,確認可以安全丟棄後再執行 XACK

除錯儲存於 Redis hash 的功能旗標推出設定

👤 使用 Redis 作為旗標後端的平台團隊 ⏱ ~10 min beginner

何時使用: 旗標對部分使用者的行為與預期不符。

步驟
  1. 檢查旗標 hash
    HGETALL flags:new-checkout,顯示所有欄位與值。✓ 已複製
    → 旗標定義內容
  2. 查看覆寫集合
    SMEMBERS flags:new-checkout:allowlistflags:new-checkout:blocklist。使用者 42 是否在其中?✓ 已複製
    → 成員查詢結果
  3. 修正並驗證
    將使用者 42 SADD 至白名單。重新 HGETALL 確認旗標其他欄位未被更動。✓ 已複製
    → 白名單已更新;其他欄位不變

結果: 旗標狀態符合預期設定,並留有已驗證的變更紀錄。

注意事項
  • 未協調就直接寫入旗標金鑰,可能破壞其他管理員正在進行的測試 — 寫入前先在 #platform 頻道公告;更好的做法是使用有變更紀錄的管理後台
搭配使用: sentry

組合

與其他 MCP 搭配,撬動十倍槓桿

redis + sentry

將快取金鑰與 Sentry 中引用它的錯誤事件相互關聯

Sentry 事件顯示快取金鑰 user:profile:42 遺失。GET 該金鑰,檢查其 TTL,確認是被驅逐還是從未填充。✓ 已複製
redis + postgres

比對 Redis 快取的計數與 Postgres 資料來源的真實值

從 Redis GET stats:active_users:today。在 Postgres 執行 SELECT COUNT(*) FROM users WHERE last_seen > ...。回報數值差異。✓ 已複製
redis + filesystem

匯出金鑰快照供離線分析

SCAN 所有符合 session:* 的金鑰,將金鑰、TTL 及大小匯出至 /tmp/session-audit.jsonl。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
scan pattern: str, count?: int 依模式探索金鑰(務必使用此方式,絕不使用 KEYS) free
type key: str 對未知金鑰執行任何資料型別相關操作前,先確認型別 free
get / set / del key, value?, ex? 字串操作 — 快取、計數器、鎖 free
hgetall / hset / hdel key, field?, value? 以 hash 形式儲存的結構化記錄 free
sadd / smembers / sismember / srem key, member(s) 封鎖名單、白名單、成員資格管理 free
zadd / zrange / zrangebyscore key, score+member(s) 排行榜、優先佇列 free
xadd / xrange / xread / xpending / xclaim / xack stream ops 基於 Redis Streams 的工作佇列 free
ttl / expire / persist key, seconds? 查看或設定過期時間 free
info / memory_usage section? / key 容量與效能檢查 free

成本與限制

運行它的成本

API 配額
受限於你的 Redis 實例的每秒指令數上限(非 MCP 限制)
每次呼叫 Token 數
大多數指令 <200 tokens;HGETALL/LRANGE 會隨資料量等比增長
費用
使用現有 Redis 完全免費。Redis Cloud 免費方案提供 30MB。
提示
SCAN 時務必設定合理的 count 值(預設 10 在大規模場景下很慢;建議設為 1000 作為批次大小)。

安全

權限、密鑰、影響範圍

最小權限: ACL user with `~pattern` and `+@read` for read-only work
憑證儲存: REDIS_URL(含密碼)存放於環境變數;建議搭配 rediss:// 啟用 TLS 加密
資料出站: 直接透過 TCP 連線至你的 Redis 端點;不經過第三方代理
切勿授予: FLUSHALL FLUSHDB CONFIG SET SHUTDOWN

故障排查

常見錯誤與修復

NOAUTH Authentication required

REDIS_URL 缺少密碼。請使用 redis://:password@host:6379 格式。

驗證: redis-cli -u $REDIS_URL PING
MOVED 1234 other-host:6379 (Redis Cluster)

MCP 使用單機模式客戶端,不支援叢集模式。請改用支援叢集的代理,或連線至非叢集的 Redis 端點。

ERR unknown command 'JSON.GET'

此指令僅 Redis Stack 支援。請升級至 Redis Stack / Redis Cloud,或改用 hash 儲存資料。

驗證: redis-cli MODULE LIST
OOM command not allowed when used memory > 'maxmemory'

Redis 記憶體已滿。檢查 MEMORY STATS,驅逐不必要的資料或擴充實例規格,並對後續寫入設定 TTL。

驗證: redis-cli INFO memory

替代方案

Redis 對比其他方案

替代方案何時用它替代權衡
Memcached MCP只需要單純的 KV 快取,不需要複雜資料結構功能介面小得多;不支援 list/set/stream
DragonflyDB MCP需要相容 Redis 但具備多執行緒能力的方案較新,部分模組尚未完整支援

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills