mcp-redis

library1.2.5jsnpmunverified

MCP server for Redis operations (standalone and cluster) via stdio and Streamable HTTP. Version 1.2.5. Provides CRUD tools for key-value, list, hash, set, and diagnostic commands. Supports Redis Cluster with automatic node discovery. Designed for LLM agents using the Model Context Protocol. Uses ioredis under the hood. ESM-only.

database

npm install mcp-redis

package ↗

INSTALL

IMPORT

SIG · MCP-REDIS

mcp-redis

databasejavascriptv1.2.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mcp-redis

✓ npx mcp-redis or use via MCP config

✗ require('mcp-redis')

Package is a CLI tool, not a library. Import by running npx or via MCP config.

REDIS_URL

✓ process.env.REDIS_URL

✗ process.env.REDIS

Environment variable for standalone Redis connection URL.

REDIS_CLUSTER_NODES

✓ process.env.REDIS_CLUSTER_NODES

✗ process.env.REDIS_NODES

Comma-separated list of Redis cluster node URLs. Overrides REDIS_URL.

Shows how to configure mcp-redis as an MCP server with environment variables for standalone Redis.

// Add to MCP config (e.g., claude_desktop_config.json): { "mcpServers": { "redis": { "command": "npx", "args": ["-y", "mcp-redis"], "env": { "REDIS_URL": process.env.REDIS_URL ?? "redis://localhost:6379", "REDIS_USERNAME": process.env.REDIS_USERNAME ?? "", "REDIS_PASSWORD": process.env.REDIS_PASSWORD ?? "" } } } } // Then use MCP client to call tools like redis_keys, redis_get, redis_set, redis_del, redis_command, redis_info.

Debug

Known issues

breakingREDIS_CLUSTER_NODES env var overrides REDIS_URL; both may be ignored if missing.

fix

Set either REDIS_URL (standalone) or REDIS_CLUSTER_NODES (cluster), not both.

affects: >=1.0.0

breakingProgrammatic import of mcp-redis as a module is unsupported. Only CLI usage via npx or MCP config.

fix

Use npx -y mcp-redis or embed as an MCP server in your application's config.

affects: >=1.0.0

gotchaRedis username and password are optional but may cause connection failures if required by server but omitted.

fix

Set REDIS_USERNAME and REDIS_PASSWORD when Redis requires authentication.

affects: >=1.0.0

deprecatedNo direct npm package import; future versions may expose SDK exports—check changelog.

fix

Currently only usable via CLI; watch for breaking changes if programmatic API is added.

affects: >=1.2.0

gotchaCluster mode requires at least one reachable node in REDIS_CLUSTER_NODES; ordering matters for initial connection.

fix

Provide comma-separated valid node URLs (e.g., redis://host1:7000,redis://host2:7001).

affects: >=1.0.0

Errors

Common errors & fixes

Error: Redis connection failed: connect ECONNREFUSED 127.0.0.1:6379

Redis server not running or wrong host/port.

fix

Start Redis or set REDIS_URL to correct address.

Error: Cluster all slots are not covered

Redis cluster nodes are not fully configured (e.g., missing replicas or slots).

fix

Ensure all cluster nodes are registered and slots assigned. Use redis-cli --cluster fix.

TypeError: redis_get is not a function

Attempting to import mcp-redis as a JavaScript module.

fix

Do not import mcp-redis directly; only use via MCP server configuration or npx CLI.

Error: NOAUTH Authentication required

Redis server requires password but REDIS_PASSWORD is not set or incorrect.

fix

Set REDIS_PASSWORD (and optionally REDIS_USERNAME) environment variables.

Upgrade

Version history

1.2.5latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredMCP server framework

ioredisrequiredRedis client for standalone and cluster connections

Agent activity

4 hits · last 30 days

node

Resources

packagemcp-redis ↗