Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

MCP server

Last updated

hotkv-mcp is a Model Context Protocol server for HotKV. It lets an AI assistant or agent work with your HotKV server through a fixed set of tools: read and write keys, keep conversation memory and notes, log events, store prompt templates and search documents.

It is open source (Apache-2.0): github.com/hotkv-ltd/hotkv-mcp.

There is no tool that runs an arbitrary command, so an agent cannot flush a database, change the server’s configuration or read another tenant’s data.

Install

Section titled “Install”
Terminal window
pip install hotkv-mcp

Or run it without installing, with uv:

Terminal window
uvx hotkv-mcp --url hotkv://localhost:6379

It needs Python 3.10 or newer.

Connect a client

Section titled “Connect a client”

The server speaks stdio by default, so a client starts it as a subprocess.

Claude Code

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

Claude Desktop, Cursor and other clients that read an mcpServers file

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

Keep the password in HOTKV_URL or in the client’s secret store, not on the command line, where other users of the machine can see it. Use hotkvs:// for a TLS connection.

Options

Section titled “Options”
Option Environment Meaning
--url URL HOTKV_URL Server to use. Default hotkv://127.0.0.1:6379. hotkvs://, redis:// and rediss:// also work.
--read-only HOTKV_MCP_READ_ONLY=1 Offer read tools only.
--namespace PREFIX HOTKV_MCP_NAMESPACE Store everything under PREFIX:. The agent never sees the prefix and cannot reach other names.
--max-value-bytes N HOTKV_MCP_MAX_VALUE_BYTES Cut longer values. Default 65536.
--max-items N HOTKV_MCP_MAX_ITEMS Most keys, rows or hits per call. Default 200.
--transport stdio (default) or streamable-http.
--host, --port Bind address for streamable-http. Default 127.0.0.1:8000, path /mcp.

Command line options win over the environment.

Namespaces are plain prefixes. Give each agent a namespace that is not itself a prefix of another (agent-a and agent-b, not agent and agent:b), or the shorter one can reach the longer one’s names.

Tools

Section titled “Tools”
Group Tools
Server server_info
Keys get, set, delete, key_info, scan
Hashes hash_get, hash_set
Lists list_range, list_push
Conversation memory memory_append_message, memory_get_messages, memory_clear_messages
Working notes memory_set_note, memory_get_note, memory_list_notes
Event log memory_log_event, memory_query_events
Rolling summary memory_set_summary, memory_get_summary
Prompt registry prompt_save, prompt_get, prompt_versions, prompt_list
Document search rag_create, rag_ingest, rag_search, rag_list

Each tool says in its annotations whether it only reads, writes or deletes, so a client can ask for approval before the destructive ones. With --read-only the tools that write are not registered at all, so the agent cannot see them.

Results are capped by --max-value-bytes and --max-items. A value that was cut comes back with truncated set, so a huge value cannot flood the model’s context.

Licensing

Section titled “Licensing”

The key, hash and list tools work on any HotKV server. The memory, prompt registry and document search tools use the AI engines of the server (agent memory, the prompt registry and RAG), which need a license that includes them. Without one, those tools answer “This HotKV server is not licensed for that feature” and the others keep working.

rag_search ranks by keyword relevance, so it needs no embedding model.

Running over HTTP

Section titled “Running over HTTP”
Terminal window
hotkv-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Next steps

Section titled “Next steps”