Skip to content

AI Assistants (MCP)

Valkey Admin includes a read-only MCP server. AI assistants that support MCP, such as Claude Code and Cursor, can use it to read server info, big keys and hot keys from your Valkey deployments.

AI assistant --HTTP--> MCP server --WebSocket--> Valkey Admin server --> Valkey

The MCP server never connects to Valkey directly. It talks to the Valkey Admin server like one more browser tab, and the server does the Valkey work.

The MCP server needs Web mode. It is not available in the desktop app, or in Kubernetes mode in this release.

Tool Returns Parameters Standalone Cluster
get_server_info INFO and memory data None Yes Connected node only
get_big_keys Largest keys by memory topN (default 20), scanLimit per node (default 10000) Yes All nodes
get_hot_keys Most frequently accessed keys count (default 20) No All nodes

get_hot_keys requires cluster mode, cluster-slot-stats-enabled yes and an LFU maxmemory-policy such as allkeys-lfu. See Hot Slots Detection.

get_big_keys adds load to each node it scans. scanLimit applies per node, so a three-node cluster with the default limit can scan up to about 30,000 keys.

Set VALKEY_ADMIN_MCP_ENABLED=true, a token of at least 32 characters and the Valkey deployments the assistant may read:

Terminal window
MCP_TOKEN="$(openssl rand -hex 32)"
echo "$MCP_TOKEN" # keep it: the assistant sends this token
docker run -d --name valkey-admin -p 127.0.0.1:8080:8080 \
-e VALKEY_ADMIN_MCP_ENABLED=true \
-e VALKEY_ADMIN_MCP_TOKEN="$MCP_TOKEN" \
-e VALKEY_ADMIN_MCP_TARGETS="prod=valkey-prod:6379,cache=valkeys://valkey-cache:6380" \
-e VALKEY_ADMIN_MCP_USERNAME=mcp_readonly \
-e VALKEY_ADMIN_MCP_PASSWORD="<password>" \
valkey/valkey-admin

The Valkey Admin server starts the MCP server and serves each target on port 8080, at /mcp/<target>. Here those are http://localhost:8080/mcp/prod and http://localhost:8080/mcp/cache. Every request must send Authorization: Bearer <token>, with the token printed above.

The server does not start the MCP server unless both the token and the targets are set, and its log names what is missing. Target hosts are resolved inside the container, so use host.docker.internal for Valkey on your machine, or the service name for Valkey in the same Compose project. On Linux, host.docker.internal resolves only with Docker Desktop; with Docker Engine, add --add-host=host.docker.internal:host-gateway to docker run.

See MCP Server for every variable.

Add one entry per target. For a cluster, one target is enough: point it at any node, and Valkey Admin finds the other nodes.

Terminal window
claude mcp add --transport http valkey-prod http://localhost:8080/mcp/prod \
--header "Authorization: Bearer <token>"

Other assistants accept the same settings as JSON, though the file location and exact format vary:

{
"mcpServers": {
"valkey-prod": {
"type": "http",
"url": "http://localhost:8080/mcp/prod",
"headers": { "Authorization": "Bearer <token>" }
}
}
}

In Claude Code, run /mcp to confirm the entry is connected, then ask for the big keys of that deployment.

Connect as a dedicated Valkey user that can read but not write. The rule grants @read and @connection, then removes @dangerous, which takes away commands such as KEYS, CLIENT KILL and CLIENT LIST. It then adds back only what the tools and the metrics collector use: INFO and COMMANDLOG GET, which are in @dangerous, and MEMORY STATS, CLUSTER SLOTS and CLUSTER SLOT-STATS, which are not in @read. Rules apply in order, so keep -@dangerous after the category grants:

ACL SETUSER mcp_readonly on >password ~* +@read +@connection -@dangerous +info +memory|stats +cluster|slots +cluster|slot-stats +commandlog|get +command|info

The MCP user is a separate Valkey identity, so Valkey Admin runs its own metrics collectors for it, about 150 MB of RAM per primary node, even when the UI already monitors the same deployment. See Resource Sizing.

  • Writes, FLUSHALL, CONFIG GET, CONFIG SET, KEYS, MONITOR and CLIENT KILL stay blocked.
  • Create the user on every node. A cluster does not replicate ACL users.
  • Persist it with ACL SAVE when the node uses an ACL file, or CONFIG REWRITE when users live in valkey.conf. Otherwise it is lost on restart.
  • On ElastiCache, create the user in the console or with the AWS CLI. Use the rule without the user name and >password as its access string, and add the user to the cluster’s user group. User groups need in-transit encryption, so use valkeys:// in the target.
  • If get_big_keys fails with NOPERM, the error names the command; add it with +<command>. get_server_info and get_hot_keys do not pass the NOPERM message through yet and fail with a generic error, so check the user against the rule above.
  • Read-only: the tools take no raw commands, and the MCP server sends only an allowlist of read actions to the Valkey Admin server.
  • Token: every request must send VALKEY_ADMIN_MCP_TOKEN. Requests with a non-local Origin are refused.
  • Server-chosen targets: an assistant can reach only the listed deployments, with the MCP server’s own credentials. It never sends a host or password, and X-Valkey-* connection headers are refused.
  • Least privilege: Valkey’s ACL is the real access control, so use the read-only user, not default.
  • Data sent to the assistant: tool results, including key names, go to your AI assistant and its model provider.

Valkey Admin itself has no authentication, so keep publishing port 8080 on loopback, as in the example above. See Docker Deployment.

Error What to do
401 Unauthorized Send Authorization: Bearer <token> with the value of VALKEY_ADMIN_MCP_TOKEN
404 Unknown MCP target Use /mcp/<name> with a name from VALKEY_ADMIN_MCP_TARGETS
400 X-Valkey-* headers are not accepted ... Remove the X-Valkey-* headers from the assistant. The URL chooses the deployment
404 from /mcp VALKEY_ADMIN_MCP_ENABLED is not true
503 from /mcp The MCP server is not running. The Valkey Admin server log says why: a missing token or targets, a short token or an invalid target entry
No reply from Valkey Admin for ... The request passed the 10-second limit. Lower scanLimit and try again
Hot keys use cluster slot stats, which need ... Apply the settings listed in the error
Metrics server not started Metrics are still starting. Try again in a few seconds
NOPERM ... The Valkey user lacks a command the tools use. See Read-only Valkey user
WRONGPASS ... Check VALKEY_ADMIN_MCP_USERNAME and VALKEY_ADMIN_MCP_PASSWORD, and that the user exists on every node

npm run dev starts the MCP server on http://localhost:8081/mcp next to the frontend and the server, without a token or targets. There, the assistant chooses the deployment with X-Valkey-* headers. See the MCP server README.