Redis MCP: Подключите ИИ-агента к вашей базе данных

Redis MCP позволяет ИИ-клиенту вызывать инструменты, которые читают и изменяют данные в Redis. Чтобы подключить собственную базу данных, запустите официальный redis-mcp-server, укажите ему адрес Redis и учетные данные с правами только на чтение, а затем зарегистрируйте этот процесс в Cursor или Claude Desktop.

Это руководство поможет настроить подключение с использованием двух небольших демо-ключей. Вы прочитаете строку и хеш, проверите TTL и убедитесь, что Redis отклоняет запись. Вы можете начать на своем компьютере, а затем использовать тот же подход с выделенным экземпляром Managed Redis в Lizard.

Протестировано 27 сентября 2026 года по времени Дубая: Python 3.12.10, Redis 8.8.0, redis-mcp-server 0.5.1, MCP Python SDK 1.30.0 и redis-py 8.1.0. Скрипт прошел 14 проверок на изолированном локальном процессе Redis через MCP по stdio. Мы не проверяли базу на хостинге, TLS или интерфейсы Cursor и Claude Desktop. Эти шаги настройки описаны по документации продуктов. Мы подготовили руководство с помощью ИИ; тестовый скрипт и результаты доступны ниже.

Выберите сервер Redis MCP для доступа к данным

Официальный сервер Redis MCP подключается к конечной точке Redis. Его инструменты включают чтение строк и хешей, запись, проверку ключей и информацию о сервере. Redis обеспечивает соблюдение прав доступа предоставленных вами учетных данных.

Существует несколько инструментов Redis, в названии которых есть MCP:

Мы используем первый вариант. Подключение к документации не даст вашему агенту доступ к вашим ключам. Redis описывает это различие в своем руководстве по настройке агента.

Процесс MCP работает на том же компьютере, что и ваш клиент, и обменивается данными через стандартный ввод и вывод, или stdio. Он открывает отдельное сетевое подключение к Redis. Публичный HTTP-адрес для MCP здесь не нужен. Зеленый индикатор подключения в клиенте показывает только то, что процесс MCP запущен; вызов инструмента все равно должен доказать, что аутентификация Redis и доступ к данным работают.

1. Подготовьте небольшую базу данных Redis

Используйте выделенный учебный экземпляр с синтетическими данными. Вам понадобится Python 3.10 или новее, uv и доступ к серверу Redis. Для локального варианта также требуется redis-server в вашем PATH.

Скачайте эти файлы в новую папку для примера:

• requirements.txt: закрепленные пакеты Python.
• setup.py: создает два ключа и пользователя только для чтения, затем записывает конфигурацию MCP.
• verify.py: запускает собственный локальный процесс Redis и тестирует подключение MCP.
• validation.json: результаты тестового запуска из этого руководства.

В macOS или Linux создайте окружение Python:

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

В отдельном терминале запустите временный экземпляр Redis:

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

Оставьте этот терминал открытым. Этот локальный экземпляр не сохраняет данные и слушает только loopback-интерфейс. Остановите его с помощью Ctrl+C, когда закончите. Если порт 6391 уже занят другим процессом, выберите свободный порт и задайте соответствующий ADMIN_REDIS_URL перед запуском настройки.

В папке с примером выполните:

.venv/bin/python setup.py

Скрипт настройки по умолчанию подключается к redis://127.0.0.1:6391/0. Он создает:

Он также создает пользователя mcp_reader со случайным паролем. Он отказывается заменять существующего пользователя или демо-ключи, поэтому повторный запуск на том же экземпляре останавливается с объяснением.

Скрипт сохраняет mcp.local.json с абсолютным путем к установленному серверу MCP. Файл содержит пароль пользователя. Держите его в секрете и добавьте эти пути в .gitignore демо-проекта перед любыми коммитами:

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

В Windows используйте .venv\Scripts\python.exe для команд Python. Скрипт выбирает подходящий путь к исполняемому файлу для сгенерированной конфигурации. Мы выполнили автоматические проверки в macOS.

2. Настройте права пользователя

Скрипт применяет эту политику Redis ACL. Это синтаксис команд Redis с примером пароля; скрипт настройки генерирует для вас настоящий пароль:

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

Правила разрешают чтение известных строк и хешей в mcpdemo:*, а также проверки типа и TTL. Они запрещают запись, команды администрирования, pub/sub и перечисление ключей. Справочник по Redis ACL объясняет каждое правило.

Промпт только для чтения не обеспечивает доступ только для чтения. Это делают учетные данные базы данных. Сервер MCP все еще может предлагать инструменты записи; Redis должен отклонять их выполнение для этого пользователя. Оставьте включенными запросы на подтверждение в клиенте как дополнительную проверку того, какие вызовы выполняются.

Почему политика не разрешает SCAN

Шаблон ключа ACL ограничивает доступ к значениям ключей. Он не заставляет SCAN возвращать только имена ключей, соответствующие этому шаблону. В нашем тесте предоставление +scan позволило mcp_reader обнаружить имя private:sentinel, хотя он не мог прочитать значение этого ключа. Отзыв SCAN снова заблокировал перечисление.

Начните с известных демо-ключей. Если позже вы разрешите просмотр на отдельном экземпляре, который не содержит посторонних данных, используйте scan_keys небольшими итерациями и следуйте за возвращаемым курсором, пока он не станет равен нулю. COUNT задаёт примерный объём работы за один вызов, а не жесткий лимит результатов. Смотрите справочник по SCAN. Политика по умолчанию в этом руководстве намеренно отклоняет как scan_keys, так и scan_all_keys.

3. Добавьте Redis MCP в Cursor или Claude Desktop

Откройте созданный mcp.local.json локально. Он имеет такой вид:

{
  "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"
      }
    }
  }
}

Используйте реальный сгенерированный файл, а не заполнители выше. Объедините запись redis-demo с существующим объектом mcpServers вашего клиента; сохраните любые другие серверы, которые уже там есть.

Cursor: используйте .cursor/mcp.json в демо-проекте или ~/.cursor/mcp.json для настройки на уровне пользователя. Проверьте сервер в настройках MCP клиента и включите его для проекта. Cursor документирует расположение файлов в своем руководстве по интеграции MCP.

Claude Desktop: объедините запись в claude_desktop_config.json. В macOS этот файл находится в ~/Library/Application Support/Claude/. Перезапустите приложение после сохранения. Следуйте руководству по настройке клиента Redis для текущих шагов клиента.

В этом руководстве хост, порт и база данных передаются как явные аргументы. В протестированной точке входа командной строки 0.5.1 значения CLI по умолчанию перезаписывают эти настройки, если вы предоставляете только переменные окружения. Поэтому предоставление только REDIS_HOST может привести к тому, что процесс попытается использовать 127.0.0.1. Имя пользователя и пароль в конфигурации выше используют поддерживаемые переменные REDIS_USERNAME и REDIS_PWD.

4. Проверьте подключение

Попросите вашего клиента явно использовать инструменты Redis. Одобряйте запрошенные чтения и проверяйте вывод инструмента, прежде чем полагаться на сводку модели.

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.

Ожидаемые результаты:

• get возвращает ready.
• hgetall возвращает два синтетических поля.
• type возвращает hash и положительный TTL ниже 3 600 секунд.

Официальный инструмент type включает TTL в свой ответ. В нашем запуске он вернул:

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

Ваше число будет отличаться. TTL равный -2 означает, что ключ не существует; -1 означает, что он существует без срока действия. Если прошло больше часа, срок действия демо-данных мог истечь. Авторизованный администратор может заново создать ключи, или вы можете запустить новый локальный экземпляр и снова выполнить настройку.

Затем используйте одноразовое демо, чтобы проверить ограничение:

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.

Наш вызов MCP вернул User mcp_reader has no permissions to run the 'set' command, а отдельное чтение по-прежнему возвращало ready. Это подтверждает как отказ, так и неизмененное значение. Некоторые инструменты Redis MCP возвращают ошибку в виде текста, поэтому проверяйте содержимое ответа, даже когда сам вызов MCP завершается.

Вы можете воспроизвести базовые проверки протокола без API-ключа модели:

.venv/bin/python verify.py

Скрипт запускает собственный процесс Redis на свободном порту loopback. Он не принимает URL вашей базы данных. Он проверяет аутентификацию, запуск MCP, предлагаемые инструменты, чтение, TTL, заблокированную запись, неизмененные данные, другой префикс ключа, отсутствующие ключи и поведение SCAN, описанное выше. Он останавливает только тот процесс, который создал, и сохраняет validation.json рядом со скриптом.

5. Подключите выделенный экземпляр Managed Redis

Для общей базы данных приложения создайте Managed Redis на панели управления проектом и следуйте руководству по подключению. Используйте отдельный учебный экземпляр для этого упражнения. Скопируйте его URL подключения в приватный локальный файл .env под именем ADMIN_REDIS_URL; никогда не вставляйте эти учетные данные администратора в чат с ИИ.

Загрузите свой собственный доверенный файл и запустите настройку из папки с примером:

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

Скрипт настройки использует эти учетные данные для создания синтетических ключей и пользователя. Его сгенерированная конфигурация MCP содержит только новые учетные данные пользователя. Он извлекает хост, порт и базу данных из URL и включает проверку сертификата TLS для адресов rediss://. Параметры запроса и пути к пользовательским сертификатам требуют отдельной конфигурации; скрипт останавливается, а не пытается их угадать.

Конечная точка должна быть доступна с компьютера, на котором запущен MCP. Обычный URL redis:// не имеет транспортного шифрования. Используйте доверенный приватный маршрут или проверенную конечную точку TLS там, где это возможно; изменение префикса URL не добавляет поддержку TLS на сервер. Текущее руководство по Managed Redis показывает подключения redis://, поэтому не предполагайте, что оно предоставляет публичную конечную точку TLS.

Создание пользователя ACL также требует, чтобы провайдер разрешал ACL SETUSER. Если провайдер запрещает это, используйте его поддерживаемые средства управления пользователями перед подключением агента. Не помещайте пароль администратора в конфигурацию MCP в качестве обходного пути.

Изменения Redis ACL, сделанные во время выполнения, требуют механизма сохранения, чтобы пережить перезапуск Redis. Текущая конфигурация запуска Managed Redis не объявляет файл ACL, поэтому относитесь к этому демо-пользователю как к временному и проверяйте его после перезапусков. Не предполагайте, что сохранение AOF сохраняет пользователей ACL. Храните протестированные разрешения в вашем процессе настройки и изучите руководство по хранению и восстановлению для других ограничений сервиса.

Исправление частых ошибок подключения Redis MCP

Что создавать после успешного подключения

Используйте эту настройку для проверки учебной сессии, времени жизни записи в кеше или отладки сохраненного контекста агента. Результаты инструментов могут попадать в ваш разговор с моделью, поэтому выбирайте, какие данные агент может читать, прежде чем подключать реальное приложение.

Если вы хотите, чтобы приложение сохраняло воспоминания автоматически, перейдите к статье Память ИИ-агента с Redis. Если вашему агенту нужны реляционные данные, используйте отдельную роль для чтения в Postgres MCP.

Начните с Managed Redis, подключите пользователя только для чтения и проверьте одно успешное чтение и одну отклоненную запись перед расширением набора инструментов.