適用於代理記憶體的 MCP 伺服器：將 Claude Code 連接到 HotKV

MCP 伺服器，是讓 AI 助理擁有比單次聊天更持久的記憶的最簡單方式。Claude Code、Cursor 與類似的用戶端，一旦聊天結束就會失去聊天的上下文。為了解決這點而直接讓它們存取原始資料庫，風險很高。hotkv-mcp 是我們為 HotKV 提供的開源 MCP 伺服器。它為助理提供一組固定的工具，涵蓋筆記、對話歷史、事件日誌、提示詞範本與文件搜尋，除此之外什麼都不提供。

簡而言之。 hotkv-mcp 是採用 Apache-2.0 授權的 MCP 伺服器，透過 28 個固定工具，將 Claude Code、Cursor、VS Code 或您自己的代理連接到 HotKV 伺服器。沒有任何工具能執行任意指令，因此助理無法清空資料或更改設定。唯讀模式會移除所有寫入工具，命名空間則把代理限制在單一鍵前綴內。以 pip install hotkv-mcp 安裝，或用 uvx 執行。

什麼是 Model Context Protocol

Model Context Protocol，簡稱 MCP，是一個開放標準，用於將 AI 應用程式連接到資料來源、工具與工作流程等外部系統。該專案的簡介把它比喻為 AI 應用程式的 USB-C 連接埠。以 MCP 的術語來說，應用程式是用戶端，而它連接的每個系統，都由一台伺服器對外提供。

對記憶體而言，這表示助理呼叫一個具名的工具，例如儲存筆記的工具。這個工具可以做什麼，由伺服器決定。模型永遠不會取得自己的資料庫連線。

HotKV MCP 伺服器提供什麼

這台伺服器把 HotKV 的代理記憶體、提示詞登錄庫與文件搜尋，包裝成 28 個工具。每個工具都在其 MCP 註解中宣告自己只讀取、寫入還是刪除。用戶端就可以在執行具破壞性的工具之前，先要求核准。

這些記憶體工具對應到AI 代理記憶體一文所述的儲存區，也就是對話歷史、工作筆記與事件日誌。依嵌入進行的語意回想並未提供。rag_search 依關鍵字相關性排序，所以不需要嵌入。

鍵、雜湊與清單工具可搭配任何 HotKV 伺服器使用。記憶體、提示詞與文件搜尋工具使用 HotKV 的 AI 引擎，需要包含這些引擎的授權。沒有授權時，這些工具會傳回一則訊息，說明伺服器未獲授權使用該功能。鍵相關的工具則仍可正常運作。HotKV Cloud 的 Performance 與 Scale 執行個體包含 AI 引擎，詳見 AI 頁面。

安裝與連接

這台伺服器需要 Python 3.10 或更新版本。它是針對 HotKV 伺服器 0.3.0 與官方的 hotkv-client 套件所撰寫，PyPI 上有 1.0.0 版。可以用 pip 安裝，或用 uv 免安裝直接執行。

pip install hotkv-mcp
uvx hotkv-mcp --url hotkv://localhost:6379

Claude Code

只要一個指令即可加入。如 Claude Code MCP 文件所述，-- 用來將 Claude Code 自己的選項與啟動伺服器的指令分開。

claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379

Cursor 與 Claude Desktop

會讀取 mcpServers 檔案的用戶端，以 JSON 項目的形式使用同一台伺服器。請把密碼放在 HOTKV_URL 環境變數或用戶端的機密儲存空間中。指令列對同一台機器的其他使用者是可見的。若要使用 TLS 連線，請用 hotkvs://。

{
  "mcpServers": {
    "hotkv": {
      "command": "uvx",
      "args": ["hotkv-mcp", "--read-only"],
      "env": { "HOTKV_URL": "hotkv://:your-password@localhost:6379" }
    }
  }
}

確認它正常運作

執行 claude mcp list，確認伺服器已註冊。接著請助理呼叫 server_info 工具。它會傳回 HotKV 的版本與記憶體用量，若未設定命名空間，還會傳回鍵的數量。它也會回報伺服器是否為唯讀，以及限制在哪個命名空間。這可以確認您的防護措施已經生效。

讓代理待在安全的範圍內

能夠呼叫工具的模型，也可能被誘導濫用這些工具，因此限制比功能更重要。

沒有任意指令

沒有任何工具能執行原始指令。助理無法清空資料庫或更改伺服器的設定，因為這 28 個工具都不做這些事。它可以讀取這些工具所能觸及的任何鍵，這正是下方命名空間之所以重要的原因。

唯讀模式

--read-only 會移除所有會寫入的工具，包括 set、delete、hash_set、list_push、會新增或清除的記憶體工具、prompt_save、rag_create 與 rag_ingest。代理甚至看不到它們。適用於只應查閱記憶、絕不該修改的助理。

命名空間與大小上限

--namespace PREFIX 會把所有內容儲存在該前綴之下。代理永遠看不到這個前綴，也無法觸及其他名稱。請為每個代理指定不是其他代理前綴開頭的前綴。請用 agent-a 與 agent-b，而不要用 agent 與 agent:b，否則較短的那個可以觸及較長那個的名稱。

結果也有上限。--max-value-bytes 會截斷過長的值並標示為已截斷，預設為 65,536 位元組。--max-items 限制一次呼叫傳回的鍵、清單項目或命中的數量，預設為 200。因此單一巨大的值，不會灌爆模型的上下文。讀取整個雜湊並不受項目數上限限制，所以請不要把大型雜湊放進代理的命名空間。

HTTP 傳輸沒有登入機制

預設的 stdio 傳輸，是由用戶端以子行程的方式啟動。若要共用，可以執行 hotkv-mcp --transport streamable-http，它會在 127.0.0.1:8000 的 /mcp 監聽。它不會驗證呼叫者。請讓它保持在 localhost，或放在會進行驗證的反向代理之後，並為它指定專屬的命名空間。

為團隊選擇設定

適合的旗標取決於每個代理的用途。下列每個選項都是命令列旗標。--read-only 與 --namespace 也有環境變數，分別是 HOTKV_MCP_READ_ONLY 與 HOTKV_MCP_NAMESPACE。

請從能完成工作的最嚴格那一列開始。之後要放寬存取很容易，但要收回代理已經寫入的內容就很難。

第一次工作階段，逐步說明

在您把真正的筆記託付給這台伺服器之前，先做一次簡短的試用，看看這些防護措施的作用。請使用一次性的命名空間，以及已獲授權使用 AI 引擎的本機 HotKV 伺服器，因為沒有該授權，記憶體工具就無法運作。

1. 以命名空間連接。 執行 claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trial。
2. 檢查限制。 請助理呼叫 server_info，並回報命名空間以及伺服器是否為唯讀。它應該回答 trial，且不是唯讀。
3. 儲存一則筆記。 請它記住測試網站位於某個位址，並以網站名稱作為筆記名稱。助理會呼叫 memory_set_note，工作階段在首次使用時建立。
4. 在新的聊天中讀回。 開始一段全新的對話，詢問該工作階段有哪些筆記。它會呼叫 memory_list_notes 與 memory_get_note，而筆記依然存在。
5. 記錄一項決定。 請它在事件日誌中記錄一項決定。它會呼叫 memory_log_event，之後 memory_query_events 會把它帶回來。
6. 移除它的寫入權限。 移除舊的項目，以 --read-only 重新連接，並重複步驟 4。讀取仍然可以運作，而會寫入的工具不再提供。

如果步驟 6 的行為如上所述，您就看到了最重要的兩項控制：命名空間與唯讀模式。

當助理儲存的內容被讀回時，請把它視為不可信的文字，如記憶體一文中的把儲存的文字視為不可信所說明。由網頁寫入的筆記可能夾帶指令。

疑難排解

• 「This HotKV server is not licensed for that feature.」 記憶體、提示詞與文件搜尋工具需要包含 AI 引擎的 HotKV 授權。沒有授權時，鍵、雜湊與清單工具仍可運作。
• 連線失敗。 檢查 URL 的配置名稱。hotkv://、hotkvs://（TLS）、redis:// 與 rediss:// 都可以使用，密碼則寫在 URL 中，格式為 hotkv://:password@host:6379。
• 值被截斷。 當結果超過 --max-value-bytes 時，會被標示為已截斷。請提高上限，或儲存較小的值。
• 缺少寫入工具。 請在伺服器的引數中尋找 --read-only，或在其環境中尋找 HOTKV_MCP_READ_ONLY。
• 助理找不到先前儲存的名稱。 請確認它使用了相同的工作階段或代理名稱，且伺服器是以與先前相同的命名空間在執行。
• 找不到 uvx。 請安裝 uv，或用 pip 安裝套件後直接啟動 hotkv-mcp。

常見問題