Redis MCP: Conecta tu agente de IA a tu base de datos

Redis MCP permite que un cliente de IA llame a herramientas que leen y cambian datos en tu base de datos Redis. Para conectar tu propia base de datos, ejecuta el redis-mcp-server oficial, dale una dirección de Redis y una credencial restringida, y luego registra ese proceso en Cursor o Claude Desktop.

Esta guía hace que esa conexión funcione con dos pequeñas claves de demostración. Leerás una cadena y un hash, inspeccionarás un TTL y comprobarás que Redis rechaza una escritura. Puedes empezar en tu ordenador y luego usar el mismo enfoque con una instancia dedicada de Managed Redis en Lizard.

Probado el 27 de septiembre de 2026, hora de Dubái: Python 3.12.10, Redis 8.8.0, redis-mcp-server 0.5.1, MCP Python SDK 1.30.0 y redis-py 8.1.0. La prueba descargable superó 14 comprobaciones contra un proceso local aislado de Redis a través de MCP sobre stdio. No probó una base de datos alojada, TLS ni las interfaces de Cursor y Claude Desktop. Esos pasos de configuración siguen la documentación del producto enlazada. Esta guía se preparó con asistencia de IA; el script de prueba y los resultados están disponibles a continuación.

Elige el servidor Redis MCP que accede a los datos

El servidor oficial de Redis MCP se conecta a un endpoint de Redis. Sus herramientas incluyen lecturas de cadenas y hashes, escrituras, inspección de claves e información del servidor. Redis aplica los permisos de la credencial que proporciones.

Hay varias herramientas de Redis con MCP en sus nombres:

Usamos la primera. Una conexión de documentación no dará a tu agente acceso a tus claves. Redis describe la distinción en su guía de configuración de agentes.

El proceso MCP se ejecuta en el mismo ordenador que tu cliente y se comunica a través de la entrada y salida estándar, o stdio. Abre una conexión de red separada a Redis. Esta configuración no necesita un endpoint HTTP público para MCP. Un indicador de conexión verde en el cliente solo muestra que el proceso MCP se inició; una llamada a la herramienta aún debe demostrar que la autenticación de Redis y el acceso a los datos funcionan.

1. Prepara una pequeña base de datos Redis

Usa una instancia de aprendizaje dedicada con datos sintéticos. Necesitas Python 3.10 o posterior, uv y acceso a un servidor Redis. La ruta local también necesita redis-server en tu PATH.

Descarga estos archivos en un nuevo directorio de demostración:

• requirements.txt: las versiones fijadas de los paquetes de Python.
• setup.py: crea dos claves y un usuario de solo lectura, luego escribe la configuración de MCP.
• verify.py: inicia su propio proceso local de Redis y prueba la conexión MCP.
• validation.json: los resultados de la prueba de esta guía.

En macOS o Linux, crea el entorno de Python:

uv venv .venv --python 3.12
uv pip install --python .venv/bin/python -r requirements.txt

En un terminal separado, inicia una instancia temporal de Redis:

redis-server --bind 127.0.0.1 --port 6391 --save "" --appendonly no

Deja ese terminal en ejecución. Esta instancia local no tiene persistencia y solo escucha en loopback. Detenla con Ctrl+C cuando termines. Si el puerto 6391 ya pertenece a otro proceso, elige un puerto libre y configura ADMIN_REDIS_URL para que coincida antes de ejecutar la configuración.

En tu directorio de demostración, ejecuta:

.venv/bin/python setup.py

El script de configuración se conecta a redis://127.0.0.1:6391/0 por defecto. Crea:

También crea el usuario mcp_reader con una contraseña aleatoria. Se niega a reemplazar un usuario existente o claves de demostración, por lo que una ejecución repetida en la misma instancia se detiene con una explicación.

El script guarda mcp.local.json con una ruta absoluta al servidor MCP instalado. El archivo contiene la contraseña del usuario de lectura. Mantenlo privado y añade estas rutas al .gitignore del proyecto de demostración antes de confirmar cualquier cambio:

.venv/
.env
mcp.local.json
.cursor/mcp.json
test-runs/

En Windows, usa .venv\Scripts\python.exe para los comandos de Python. El script elige la ruta del ejecutable correspondiente para la configuración generada. La ejecución automatizada de esta guía usó macOS.

2. Comprende los permisos del usuario de lectura

El script aplica esta política ACL de Redis. Esta es la sintaxis del comando de Redis, con una contraseña de marcador de posición; el script de configuración genera la contraseña real para ti:

ACL SETUSER mcp_reader reset on >REPLACE_WITH_RANDOM_PASSWORD ~mcpdemo:* -@all +ping +get +hget +hgetall +type +ttl

Las reglas permiten lecturas de cadenas y hashes conocidos bajo mcpdemo:*, además de comprobaciones de tipo y TTL. Deniegan escrituras, comandos de administración, pub/sub y enumeración de claves. La referencia de ACL de Redis explica cada regla.

Un prompt de solo lectura no impone el acceso de solo lectura. La credencial de la base de datos sí lo hace. El servidor MCP aún puede anunciar herramientas de escritura; Redis debería rechazar su ejecución para este usuario. Mantén habilitadas las solicitudes de aprobación del cliente como otra comprobación de qué llamadas se ejecutan.

Por qué la política no permite SCAN

Un patrón de clave ACL restringe el acceso a los valores de las claves. No hace que SCAN devuelva solo los nombres de las claves bajo ese patrón. En nuestra prueba, otorgar +scan permitió que mcp_reader descubriera el nombre private:sentinel, aunque no pudo leer el valor de esa clave. Revocar SCAN bloqueó la enumeración de nuevo.

Empieza con claves de demostración conocidas. Si más adelante permites la navegación en una instancia separada que no contiene datos no relacionados, usa scan_keys en pequeñas iteraciones y sigue el cursor devuelto hasta que se convierta en cero. COUNT es una sugerencia de trabajo, no un límite estricto de resultados. Consulta la referencia de SCAN. La política predeterminada del tutorial rechaza deliberadamente tanto scan_keys como scan_all_keys.

3. Añade Redis MCP a Cursor o Claude Desktop

Abre el mcp.local.json generado localmente. Tiene esta forma:

{
  "mcpServers": {
    "redis-demo": {
      "command": "/ABSOLUTE/PATH/redis-mcp-demo/.venv/bin/redis-mcp-server",
      "args": ["--host", "127.0.0.1", "--port", "6391", "--db", "0"],
      "env": {
        "REDIS_USERNAME": "mcp_reader",
        "REDIS_PWD": "YOUR_GENERATED_READER_PASSWORD"
      }
    }
  }
}

Usa el archivo generado real, no los marcadores de posición anteriores. Combina la entrada redis-demo en el objeto mcpServers existente de tu cliente; mantén cualquier otro servidor que ya esté allí.

Cursor: usa .cursor/mcp.json en el proyecto de demostración, o ~/.cursor/mcp.json para una configuración a nivel de usuario. Comprueba el servidor en la configuración MCP del cliente y actívalo para el proyecto. Cursor documenta las ubicaciones de los archivos en su guía de integración de MCP.

Claude Desktop: combina la entrada en claude_desktop_config.json. En macOS, ese archivo se encuentra en ~/Library/Application Support/Claude/. Reinicia la aplicación después de guardar. Sigue la guía de configuración del cliente de Redis para los pasos actuales del cliente.

Esta guía pasa el host, el puerto y la base de datos como argumentos explícitos. En el punto de entrada de línea de comandos 0.5.1 probado, los valores predeterminados de la CLI sobrescriben esa configuración si solo proporcionas variables de entorno. Por lo tanto, proporcionar solo REDIS_HOST puede dejar al proceso intentando 127.0.0.1. El nombre de usuario y la contraseña en la configuración anterior usan las variables compatibles REDIS_USERNAME y REDIS_PWD.

4. Comprueba la conexión

Pide a tu cliente que use las herramientas de Redis explícitamente. Aprueba las lecturas solicitadas e inspecciona la salida de la herramienta antes de confiar en el resumen del modelo.

Use redis-demo to get mcpdemo:status. Then use hgetall on
mcpdemo:session:42 and type on that same key. Report the raw
tool results and the remaining TTL. Do not change any data.

Los resultados esperados son:

• get devuelve ready.
• hgetall devuelve los dos campos sintéticos.
• type devuelve hash y un TTL positivo por debajo de 3.600 segundos.

La herramienta oficial type incluye el TTL en su respuesta. En nuestra ejecución devolvió:

{
  "key": "mcpdemo:session:42",
  "type": "hash",
  "ttl": 3591
}

Tu número será diferente. Un TTL de -2 significa que la clave no existe; -1 significa que existe sin caducidad. Si ha pasado más de una hora, los datos de demostración pueden haber caducado. Un administrador autorizado puede volver a crear las claves, o puedes iniciar una nueva instancia local y ejecutar la configuración de nuevo.

A continuación, usa la demostración desechable para comprobar la restricción:

Use redis-demo to try setting mcpdemo:status to changed once.
Report the exact tool result. Then read mcpdemo:status again.
Do not retry with other tools or credentials.

Nuestra llamada MCP devolvió User mcp_reader has no permissions to run the 'set' command, y una lectura separada aún devolvió ready. Esto verifica tanto la denegación como el valor inalterado. Algunas herramientas de Redis MCP devuelven un error como texto, así que inspecciona el contenido de la respuesta incluso cuando la llamada MCP en sí se complete.

Puedes reproducir las comprobaciones del protocolo subyacente sin una clave de API del modelo:

.venv/bin/python verify.py

El script inicia su propio proceso de Redis en un puerto loopback libre. No acepta la URL de tu base de datos. Comprueba la autenticación, el inicio de MCP, las herramientas anunciadas, las lecturas, el TTL, las escrituras bloqueadas, los datos inalterados, otro prefijo de clave, las claves faltantes y el comportamiento de SCAN anterior. Solo detiene el proceso que creó y guarda validation.json junto al script.

5. Conecta una instancia dedicada de Managed Redis

Para una base de datos de aplicación compartida, crea Managed Redis en el panel del proyecto y sigue la guía de conexión. Usa una instancia de aprendizaje separada para este ejercicio. Copia su URL de conexión en un archivo local privado .env bajo el nombre ADMIN_REDIS_URL; nunca pegues esa credencial de administrador en un chat de IA.

Carga tu propio archivo de confianza y ejecuta la configuración desde el directorio de demostración:

set -a
. ./.env
set +a
.venv/bin/python setup.py
unset ADMIN_REDIS_URL

El script de configuración usa esa credencial para crear las claves sintéticas y el usuario de lectura. Su configuración MCP generada contiene solo la nueva credencial del usuario de lectura. Extrae el host, el puerto y la base de datos de la URL, y añade opciones de TLS con verificación de certificados para los endpoints rediss://. Los parámetros de consulta y las rutas de certificados personalizados necesitan una configuración separada; el script se detiene en lugar de adivinarlos.

El endpoint debe ser accesible desde el ordenador que ejecuta MCP. Una URL redis:// simple no tiene cifrado de transporte. Usa una ruta privada de confianza o un endpoint TLS verificado donde esté disponible; cambiar el prefijo de la URL no añade soporte TLS a un servidor. La guía actual de Managed Redis muestra conexiones redis://, así que no asumas que proporciona un endpoint TLS público.

Crear un usuario ACL también requiere que el proveedor permita ACL SETUSER. Si el proveedor lo deniega, usa sus controles de gestión de usuarios compatibles antes de conectar el agente. No pongas la contraseña de administrador en la configuración de MCP como solución alternativa.

Los cambios de ACL de Redis realizados en tiempo de ejecución necesitan un mecanismo de persistencia para sobrevivir a un reinicio de Redis. La configuración de inicio actual de Managed Redis no declara un archivo ACL, así que trata a este usuario de demostración como temporal y verifícalo después de los reinicios. No asumas que la persistencia AOF guarda a los usuarios ACL. Mantén los permisos probados en tu proceso de configuración y revisa la guía de almacenamiento y recuperación para conocer los otros límites del servicio.

Soluciona errores comunes de conexión de Redis MCP

Qué construir después de que funcione la conexión

Usa esta configuración para inspeccionar una sesión sintética, comprobar la vida útil de una entrada de caché o depurar el contexto guardado de un agente. Los resultados de las herramientas pueden entrar en la conversación de tu modelo, así que elige qué datos puede leer el agente antes de conectar una aplicación real.

Si quieres que la aplicación guarde recuerdos automáticamente, continúa con Memoria de agente de IA con Redis. Si tu agente necesita datos relacionales, usa el rol de lector separado en Postgres MCP.

Empieza con Managed Redis, conecta el usuario de solo lectura y verifica una lectura exitosa y una escritura denegada antes de expandir el conjunto de herramientas.