Redis MCP Server

Uma interface de linguagem natural para aplicações agentivas gerenciarem e pesquisarem dados no Redis.

Documentação

Redis MCP Server

Visão geral

O Redis MCP Server é uma interface de linguagem natural projetada para aplicações agênticas gerenciarem e pesquisarem dados no Redis de forma eficiente. Ele se integra perfeitamente a clientes MCP (Model Content Protocol), permitindo que fluxos de trabalho orientados por IA interajam com dados estruturados e não estruturados no Redis. Usando este MCP Server, você pode fazer perguntas como:

"Armazene toda a conversa em um stream"
"Cacheie este item"
"Armazene a sessão com um tempo de expiração"
"Indexe e pesquise este vetor"

Recursos

Consultas em linguagem natural: Permite que agentes de IA consultem e atualizem o Redis usando linguagem natural.
Integração perfeita com MCP: Funciona com qualquer cliente MCP para comunicação suave.
Suporte completo ao Redis: Lida com hashes, listas, conjuntos, conjuntos ordenados, streams e mais.
Pesquisa e filtragem: Suporta recuperação eficiente de dados e pesquisa no Redis.
Escalável e leve: Projetado para operações de dados de alta performance.
Autenticação EntraID: Suporte nativo para autenticação do Azure Active Directory com Azure Managed Redis.
O Redis MCP Server suporta o transporte stdio transport. O suporte ao transporte stremable-http será adicionado no futuro.

Ferramentas

Este MCP Server fornece ferramentas para gerenciar os dados armazenados no Redis.

Ferramentas string para definir e obter strings com expiração. Úteis para armazenar valores de configuração simples, dados de sessão ou respostas em cache.
Ferramentas hash para armazenar pares campo-valor dentro de uma única chave. O hash pode armazenar embeddings de vetores. Úteis para representar objetos com múltiplos atributos, perfis de usuário ou informações de produto onde os campos podem ser acessados individualmente.
Ferramentas list com operações comuns para anexar e remover itens. Úteis para filas, brokers de mensagens ou manutenção de uma lista de ações mais recentes.
Ferramentas set para adicionar, remover e listar membros de conjuntos. Úteis para rastrear valores únicos como IDs de usuário ou tags, e para realizar operações de conjunto como interseção.
Ferramentas sorted set para gerenciar dados, por exemplo, rankings, filas de prioridade ou análises baseadas em tempo com ordenação por pontuação.
Funcionalidade pub/sub para publicar mensagens, criar assinaturas de canal ou padrão com estado, e ler mensagens enfileiradas usando handles de assinatura retornados. Útil para notificações em tempo real, aplicativos de chat ou distribuição de atualizações para múltiplos clientes.
Ferramentas streams para adicionar, ler, excluir, criar e destruir grupos de consumidores, e reconhecer entradas processadas em streams de dados. Úteis para event sourcing, feeds de atividades e processamento de eventos baseado em trabalhadores com grupos de consumidores do Redis Streams.
Ferramentas JSON para armazenar, recuperar e manipular documentos JSON no Redis. Úteis para estruturas de dados aninhadas complexas, bancos de dados de documentos ou gerenciamento de configuração com acesso baseado em caminho.

Ferramentas adicionais.

Ferramenta docs para pesquisar documentação, tutoriais e melhores práticas do Redis usando perguntas em linguagem natural (apoiada pela API HTTP MCP_DOCS_SEARCH_URL).
Ferramentas query engine para gerenciar índices de vetores e realizar pesquisa de vetores.
Ferramenta server management para recuperar informações sobre o banco de dados.

Instalação

O Redis MCP Server está disponível como um pacote PyPI e como instalação direta a partir do repositório GitHub.

Do PyPI (recomendado)

Configurar a versão mais recente do Redis MCP Server a partir do PyPI, como exemplo, pode ser feito importando a seguinte configuração JSON no framework ou ferramenta desejada. O comando uvx baixará o servidor em tempo real (se ainda não estiver em cache), criará um ambiente temporário e o executará.

{
  "mcpServers": {
    "RedisMCPServer": {
      "command": "uvx",
      "args": [
        "--from",
        "redis-mcp-server@latest",
        "redis-mcp-server",
        "--url",
        "\"redis://localhost:6379/0\""
      ]
    }
  }
}

Especificação de URL

O formato para especificar o argumento --url segue os esquemas redis e rediss:

redis://user:secret@localhost:6379/0?foo=bar&qux=baz

Como exemplo, você pode facilmente conectar-se a um servidor localhost com:

redis://localhost:6379/0

Onde 0 é o banco de dados lógico ao qual você deseja se conectar.

Para uma conexão criptografada ao banco de dados (por exemplo, conectando-se a um banco de dados Redis Cloud), você usaria o esquema rediss.

rediss://user:secret@localhost:6379/0?foo=bar&qux=baz

Para verificar a identidade do servidor, especifique ssl_ca_certs.

rediss://user:secret@hostname:port?ssl_cert_reqs=required&ssl_ca_certs=path_to_the_certificate

Para uma conexão não verificada, defina ssl_cert_reqs como none

rediss://user:secret@hostname:port?ssl_cert_reqs=none

Configure sua conexão usando as opções disponíveis na seção "Opções de CLI disponíveis".

Testando o pacote PyPI

Você pode instalar o pacote da seguinte forma:

pip install redis-mcp-server

E iniciá-lo usando uv o pacote em seu ambiente.

uv python install 3.14
uv sync
uv run redis-mcp-server --url redis://localhost:6379/0

No entanto, iniciar o MCP Server é mais útil quando delegado ao framework ou ferramenta onde este MCP Server está configurado.

Do GitHub

Você pode configurar a versão desejada do Redis MCP Server com uvx, o que permite executá-lo diretamente do GitHub (de um branch ou usar uma versão marcada).

É recomendado usar uma versão marcada, o branch main está em desenvolvimento ativo e pode conter mudanças que quebram a compatibilidade.

Como exemplo, você pode executar o seguinte comando para rodar a versão 0.2.0:

uvx --from git+https://github.com/redis/mcp-redis.git@0.2.0 redis-mcp-server --url redis://localhost:6379/0

Verifique as notas de versão para a versão mais recente na seção Releases. Exemplos adicionais são fornecidos abaixo.

# Run with Redis URI
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url redis://localhost:6379/0

# Run with Redis URI and SSL
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url "rediss://<USERNAME>:<PASSWORD>@<HOST>:<PORT>?ssl_cert_reqs=required&ssl_ca_certs=<PATH_TO_CERT>"

# Run with individual parameters
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --host localhost --port 6379 --password mypassword

# See all options
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --help

Instalação para desenvolvimento

Para desenvolvimento ou se você preferir clonar o repositório:

# Clone the repository
git clone https://github.com/redis/mcp-redis.git
cd mcp-redis

# Install dependencies using uv
uv venv
source .venv/bin/activate
uv sync

# Run with CLI interface
uv run redis-mcp-server --help

# Or run the main file directly (uses environment variables)
uv run src/main.py

Depois de clonar o repositório, instalar as dependências e verificar que você pode executar o servidor, você pode configurar o Claude Desktop ou qualquer outro Cliente MCP para usar este MCP Server executando o arquivo principal diretamente (ele usa variáveis de ambiente). Isso geralmente é preferido para desenvolvimento. O exemplo a seguir é para o Claude Desktop, mas o mesmo se aplica a qualquer outro Cliente MCP.

Especifique suas credenciais Redis e configuração TLS
Recupere o caminho completo do comando uv (por exemplo, which uv)
Edite o arquivo de configuração claude_desktop_config.json
- no MacOS, em ~/Library/Application\ Support/Claude/

{
    "mcpServers": {
        "redis": {
            "command": "<full_path_uv_command>",
            "args": [
                "--directory",
                "<your_mcp_server_directory>",
                "run",
                "src/main.py"
            ],
            "env": {
                "REDIS_HOST": "<your_redis_database_hostname>",
                "REDIS_PORT": "<your_redis_database_port>",
                "REDIS_PWD": "<your_redis_database_password>",
                "REDIS_SSL": True|False,
                "REDIS_SSL_CA_PATH": "<your_redis_ca_path>",
                "REDIS_CLUSTER_MODE": True|False
            }
        }
    }
}

Você pode solucionar problemas acompanhando o arquivo de log.

tail -f ~/Library/Logs/Claude/mcp-server-redis.log

Com Docker

Você pode usar uma implantação dockerizada deste servidor. Você pode construir sua própria imagem ou usar a imagem oficial Redis MCP Docker.

Se você quiser construir sua própria imagem, o Redis MCP Server fornece um Dockerfile. Construa a imagem deste servidor com:

docker build -t mcp-redis .

Finalmente, configure o cliente para criar o contêiner na inicialização. Um exemplo para o Claude Desktop é fornecido abaixo. Edite o claude_desktop_config.json e adicione:

{
  "mcpServers": {
    "redis": {
      "command": "docker",
      "args": ["run",
                "--rm",
                "--name",
                "redis-mcp-server",
                "-i",
                "-e", "REDIS_HOST=<redis_hostname>",
                "-e", "REDIS_PORT=<redis_port>",
                "-e", "REDIS_USERNAME=<redis_username>",
                "-e", "REDIS_PWD=<redis_password>",
                "mcp-redis"]
    }
  }
}

Para usar a imagem oficial Redis MCP Docker, basta substituir o nome da sua imagem (mcp-redis no exemplo acima) por mcp/redis.

Configuração

O Redis MCP Server pode ser configurado de duas maneiras: via argumentos de linha de comando ou via variáveis de ambiente. A precedência é: argumentos de linha de comando > variáveis de ambiente > valores padrão.

ACL do Redis

Você pode configurar a ACL do Redis para restringir o acesso ao banco de dados Redis. Por exemplo, para criar um usuário somente leitura:

127.0.0.1:6379> ACL SETUSER readonlyuser on >mypassword ~* +@read -@write

Configure o usuário via argumentos de linha de comando ou variáveis de ambiente.

Configuração via argumentos de linha de comando

Ao usar a interface CLI, você pode configurar o servidor com argumentos de linha de comando:

# Basic Redis connection
uvx --from redis-mcp-server@latest redis-mcp-server \
  --host localhost \
  --port 6379 \
  --password mypassword

# Using Redis URI (simpler)
uvx --from redis-mcp-server@latest redis-mcp-server \
  --url redis://user:pass@localhost:6379/0

# SSL connection
uvx --from redis-mcp-server@latest redis-mcp-server \
  --url rediss://user:pass@redis.example.com:6379/0

# See all available options
uvx --from redis-mcp-server@latest redis-mcp-server --help

Opções de CLI disponíveis:

--url - URI de conexão Redis (redis://user:pass@host:port/db)
--host - Hostname Redis (padrão: 127.0.0.1)
--port - Porta Redis (padrão: 6379)
--db - Número do banco de dados Redis (padrão: 0)
--username - Nome de usuário Redis
--password - Senha Redis
--ssl - Habilitar conexão SSL
--ssl-ca-path - Caminho para o arquivo de certificado CA
--ssl-keyfile - Caminho para o arquivo de chave SSL
--ssl-certfile - Caminho para o arquivo de certificado SSL
--ssl-cert-reqs - Requisitos de certificado SSL (padrão: obrigatório)
--ssl-ca-certs - Caminho para o arquivo de certificados CA
--cluster-mode - Habilitar modo de cluster Redis

Configuração via variáveis de ambiente

Se desejado, você pode usar variáveis de ambiente. Valores padrão são fornecidos para todas as variáveis.

Nome	Descrição	Valor padrão
`REDIS_HOST`	IP ou hostname Redis	`"127.0.0.1"`
`REDIS_PORT`	Porta Redis	`6379`
`REDIS_DB`	Banco de dados	0
`REDIS_USERNAME`	Nome de usuário padrão do banco de dados	`"default"`
`REDIS_PWD`	Senha padrão do banco de dados	""
`REDIS_SSL`	Habilita ou desabilita SSL/TLS	`False`
`REDIS_SSL_CA_PATH`	Certificado CA para verificar o servidor	None
`REDIS_SSL_KEYFILE`	Arquivo de chave privada do cliente para autenticação do cliente	None
`REDIS_SSL_CERTFILE`	Arquivo de certificado do cliente para autenticação do cliente	None
`REDIS_SSL_CERT_REQS`	Se o cliente deve verificar o certificado do servidor	`"required"`
`REDIS_SSL_CA_CERTS`	Caminho para o arquivo de certificados CA confiáveis	None
`REDIS_CLUSTER_MODE`	Habilitar modo de cluster Redis	`False`

Autenticação EntraID para Azure Managed Redis

O Redis MCP Server suporta autenticação EntraID (Azure Active Directory) para Azure Managed Redis, permitindo autenticação baseada em OAuth com gerenciamento automático de tokens.

Provedores de autenticação

Autenticação de principal de serviço - Autenticação baseada em aplicativo usando credenciais de cliente:

export REDIS_ENTRAID_AUTH_FLOW=service_principal
export REDIS_ENTRAID_CLIENT_ID=your-client-id
export REDIS_ENTRAID_CLIENT_SECRET=your-client-secret
export REDIS_ENTRAID_TENANT_ID=your-tenant-id

Autenticação de identidade gerenciada - Para aplicativos hospedados no Azure:

# System-assigned managed identity
export REDIS_ENTRAID_AUTH_FLOW=managed_identity
export REDIS_ENTRAID_IDENTITY_TYPE=system_assigned

# User-assigned managed identity
export REDIS_ENTRAID_AUTH_FLOW=managed_identity
export REDIS_ENTRAID_IDENTITY_TYPE=user_assigned
export REDIS_ENTRAID_USER_ASSIGNED_CLIENT_ID=your-identity-client-id

Credencial padrão do Azure - Descoberta automática de credenciais (recomendado para desenvolvimento):

export REDIS_ENTRAID_AUTH_FLOW=default_credential
export REDIS_ENTRAID_SCOPES=https://redis.azure.com/.default

Variáveis de configuração EntraID

Nome	Descrição	Valor Padrão
`REDIS_ENTRAID_AUTH_FLOW`	Tipo de fluxo de autenticação	Nenhum (EntraID desabilitado)
`REDIS_ENTRAID_CLIENT_ID`	ID do cliente do Service Principal	Nenhum
`REDIS_ENTRAID_CLIENT_SECRET`	Segredo do cliente do Service Principal	Nenhum
`REDIS_ENTRAID_TENANT_ID`	ID do locatário do Azure	Nenhum
`REDIS_ENTRAID_IDENTITY_TYPE`	Tipo de identidade gerenciada	`"system_assigned"`
`REDIS_ENTRAID_USER_ASSIGNED_CLIENT_ID`	ID do cliente da identidade gerenciada atribuída ao usuário	Nenhum
`REDIS_ENTRAID_SCOPES`	Escopos OAuth para Default Azure Credential	`"https://redis.azure.com/.default"`
`REDIS_ENTRAID_RESOURCE`	Identificador do recurso Azure Redis	`"https://redis.azure.com/"`

Principais Recursos

Renovação automática de token - Atualização de token em segundo plano sem intervenção manual
Fallback gracioso - Retorna à autenticação Redis padrão quando EntraID não está configurado
Múltiplos fluxos de autenticação - Suporta Service Principal, Managed Identity e Default Azure Credential
Pronto para empresas - Projetado para Azure Managed Redis com gerenciamento centralizado de identidade

Exemplo de Configuração

Para desenvolvimento local com Azure CLI:

# Login with Azure CLI
az login

# Configure MCP server
export REDIS_ENTRAID_AUTH_FLOW=default_credential
export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379

Para produção com Service Principal:

export REDIS_ENTRAID_AUTH_FLOW=service_principal
export REDIS_ENTRAID_CLIENT_ID=your-app-client-id
export REDIS_ENTRAID_CLIENT_SECRET=your-app-secret
export REDIS_ENTRAID_TENANT_ID=your-tenant-id
export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379

Para aplicações hospedadas no Azure com Managed Identity:

export REDIS_ENTRAID_AUTH_FLOW=managed_identity
export REDIS_ENTRAID_IDENTITY_TYPE=system_assigned
export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379

Existem várias maneiras de definir variáveis de ambiente:

Usando um arquivo .env: Coloque um arquivo .env no diretório do seu projeto com pares chave-valor para cada variável de ambiente. Ferramentas como python-dotenv, pipenv e uv podem carregar automaticamente essas variáveis ao executar sua aplicação. Esta é uma maneira conveniente e segura de gerenciar a configuração, pois mantém dados sensíveis fora do histórico do shell e do controle de versão (se .env estiver em .gitignore). Por exemplo, crie um arquivo .env com o seguinte conteúdo do arquivo .env.example fornecido no repositório:

cp .env.example .env

Em seguida, edite o arquivo .env para definir sua configuração Redis:

OU,

Definindo Variáveis no Shell: Você pode exportar variáveis de ambiente diretamente no seu shell antes de executar sua aplicação. Por exemplo:

export REDIS_HOST=your_redis_host
export REDIS_PORT=6379
# Other variables will be set similarly...

Este método é útil para substituições temporárias ou testes rápidos.

Registro de Logs

O servidor usa o registro padrão do Python e é configurado na inicialização. Por padrão, registra em WARNING e acima. Você pode alterar o nível de verbosidade com a variável de ambiente MCP_REDIS_LOG_LEVEL.

Valores aceitos (sem diferenciar maiúsculas de minúsculas): DEBUG, INFO, WARNING, ERROR, CRITICAL, NOTSET
Aliases suportados: WARN → WARNING, FATAL → CRITICAL
Valores numéricos também são aceitos, incluindo com sinal (por exemplo, "10", "+20")
Padrão quando não definido ou não reconhecido: WARNING

Comportamento do handler

Se o host (por exemplo, uv, VS Code, pytest) já instalou handlers de console, o servidor NÃO adicionará o seu próprio; ele apenas reduz limites de handlers excessivamente restritivos para que o nível escolhido não seja filtrado. Ele nunca aumentará o limite de um handler.
Se nenhum handler estiver presente, o servidor adiciona um único StreamHandler de stderr com um formato simples.

Exemplos

# See normal lifecycle messages
MCP_REDIS_LOG_LEVEL=INFO uv run src/main.py

# Very verbose for debugging
MCP_REDIS_LOG_LEVEL=DEBUG uvx --from redis-mcp-server@latest redis-mcp-server --url redis://localhost:6379/0

Em configurações de cliente MCP que suportam env, adicione junto com suas configurações Redis. Por exemplo:

{
  "mcpServers": {
    "redis": {
      "command": "uvx",
      "args": ["--from", "redis-mcp-server@latest", "redis-mcp-server", "--url", "redis://localhost:6379/0"],
      "env": {
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379",
        "MCP_REDIS_LOG_LEVEL": "INFO"
      }
    }
  }
}

Integrações

A integração deste MCP Server com frameworks de desenvolvimento como OpenAI Agents SDK, ou com ferramentas como Claude Desktop, VS Code ou Augment é descrita nas seções a seguir.

OpenAI Agents SDK

Integre este MCP Server com o OpenAI Agents SDK. Leia os documentos para aprender mais sobre a integração do SDK com MCP.

Instale o SDK Python.

pip install openai-agents

Configure o token OpenAI:

export OPENAI_API_KEY="<openai_token>"

E execute a aplicação.

python3.14 redis_assistant.py

Você pode solucionar problemas nos seus fluxos de trabalho de agente usando o painel OpenAI.

Augment

A maneira preferida de configurar o Redis MCP Server no Augment é usar o recurso Easy MCP.

Você também pode configurar o Redis MCP Server no Augment manualmente importando o servidor via JSON:

{
  "mcpServers": {
    "Redis MCP Server": {
      "command": "uvx",
      "args": [
        "--from",
        "redis-mcp-server@latest",
        "redis-mcp-server",
        "--url",
        "redis://localhost:6379/0"
      ]
    }
  }
}

Claude Desktop

A maneira mais simples de configurar clientes MCP é usando uvx. Adicione o seguinte JSON ao seu claude_desktop_config.json, lembre-se de fornecer o caminho completo para uvx.

Conexão Redis básica:

{
  "mcpServers": {
    "redis-mcp-server": {
        "type": "stdio",
        "command": "/Users/mortensi/.local/bin/uvx",
        "args": [
            "--from", "redis-mcp-server@latest",
            "redis-mcp-server",
            "--url", "redis://localhost:6379/0"
        ]
    }
  }
}

Azure Managed Redis com autenticação EntraID:

{
  "mcpServers": {
    "redis-mcp-server": {
        "type": "stdio",
        "command": "/Users/mortensi/.local/bin/uvx",
        "args": [
            "--from", "redis-mcp-server@latest",
            "redis-mcp-server",
            "--url", "redis://your-azure-redis.redis.cache.windows.net:6379"
        ],
        "env": {
            "REDIS_ENTRAID_AUTH_FLOW": "default_credential",
            "REDIS_ENTRAID_SCOPES": "https://redis.azure.com/.default"
        }
    }
  }
}

VS Code com GitHub Copilot

Para usar o Redis MCP Server com VS Code, você deve habilitar as ferramentas do modo agente. Adicione o seguinte ao seu settings.json:

{
  "chat.agent.enabled": true
}

Você pode iniciar a versão desejada do GitHub do Redis MCP server usando uvx adicionando o seguinte JSON ao seu arquivo mcp.json:

"servers": {
  "redis": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "--from", "redis-mcp-server@latest",
      "redis-mcp-server",
      "--url", "redis://localhost:6379/0"
    ]
  },
}

Suprimindo Mensagens de Instalação do uvx

Se você quiser suprimir mensagens de instalação do uvx que podem aparecer como avisos nos logs do cliente MCP, use o sinalizador -qq:

"servers": {
  "redis": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "-qq",
      "--from", "redis-mcp-server@latest",
      "redis-mcp-server",
      "--url", "redis://localhost:6379/0"
    ]
  },
}

O sinalizador -qq ativa o modo silencioso, que suprime mensagens "Installed X packages" que o uvx escreve no stderr durante a instalação de pacotes.

Alternativamente, você pode iniciar o servidor usando uv e configurar seu mcp.json. Isso geralmente é desejado para desenvolvimento.

// mcp.json
{
  "servers": {
    "redis": {
      "type": "stdio",
      "command": "<full_path_uv_command>",
      "args": [
        "--directory",
        "<your_mcp_server_directory>",
        "run",
        "src/main.py"
      ],
      "env": {
        "REDIS_HOST": "<your_redis_database_hostname>",
        "REDIS_PORT": "<your_redis_database_port>",
        "REDIS_USERNAME": "<your_redis_database_username>",
        "REDIS_PWD": "<your_redis_database_password>",
      }
    }
  }
}

Para mais informações, consulte a documentação do VS Code.

Dica: Você pode solicitar ao chat do Copilot para usar as ferramentas Redis MCP incluindo #redis na sua mensagem.

Nota: A partir do VS Code v1.102, os servidores MCP agora são armazenados em um arquivo mcp.json dedicado em vez de settings.json.

Testes

Você pode usar o MCP Inspector para depuração visual deste MCP Server.

npx @modelcontextprotocol/inspector uv run src/main.py

Casos de Uso de Exemplo

Assistentes de IA: Permite que LLMs busquem, armazenem e processem dados no Redis.
Chatbots e Agentes Virtuais: Recupere dados de sessão, gerencie filas e personalize respostas.
Pesquisa e Análise de Dados: Consulte o Redis para insights em tempo real e consultas rápidas.
Processamento de Eventos: Gerencie fluxos de eventos com Redis Streams.

Contribuindo

Faça um fork do repositório
Crie um novo branch (feature-branch)
Faça commit das suas alterações
Envie para o seu branch e envie um PR!

Licença

Este projeto é licenciado sob a Licença MIT.

Badges

Contato

Para perguntas ou suporte, entre em contato via GitHub Issues.

Alternativamente, você pode entrar no servidor Discord do Redis e perguntar no canal #redis-mcp-server.