# Install ```json metadata { "schema_version": 2, "title": "Install", "description": "Install and configure the Redis MCP server.", "categories": ["docs","integrate","rs"], "group": "service", "tableOfContents": {"sections":[{"id":"quick-start-with-pypi","title":"Quick Start with PyPI"},{"id":"run-from-github","title":"Run from GitHub"},{"id":"install-the-server-from-source","title":"Install the server from source"},{"id":"install-using-docker","title":"Install using Docker"},{"children":[{"id":"environment-variables","title":"Environment variables"},{"id":"command-line-options","title":"Command line options"},{"id":"entraid-authentication","title":"EntraID authentication"}],"id":"configuration","title":"Configuration"},{"id":"redis-cloud-mcp","title":"Redis Cloud MCP"},{"id":"next-steps","title":"Next steps"}]} , "codeExamples": [] } ``` The MCP server runs separately from Redis, so you will need a Redis server for it to connect to. See [Redis Cloud](https://redis.io/docs/latest/operate/rc) or [Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack) to learn how to get a test server active within minutes. When you have a Redis server available, use the instructions below to install and configure the Redis MCP server. ## Quick Start with PyPI The easiest way to use the Redis MCP Server is with [`uvx`](https://docs.astral.sh/uv/guides/tools/), which lets you run it from its [PyPI package](https://pypi.org/project/redis-mcp-server/) (see the `uv` [installation instructions](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) for more information.) ```bash # Run with Redis URI uvx --from redis-mcp-server@latest redis-mcp-server --url redis://localhost:6379/0 # Run with Redis URI and SSL uvx --from redis-mcp-server@latest redis-mcp-server --url "rediss://:@:?ssl_cert_reqs=required&ssl_ca_certs=" # Run with individual parameters uvx --from redis-mcp-server@latest redis-mcp-server --host localhost --port 6379 --password mypassword # See all options uvx --from redis-mcp-server@latest redis-mcp-server --help ``` ## Run from GitHub Running from [PyPI](#quick-start-with-pypi) is the recommended way to use the Redis MCP server, but you can also run it from a GitHub branch or a tagged release with `uvx`: ```bash # 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://:@:?ssl_cert_reqs=required&ssl_ca_certs=" # 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 ``` ## Install the server from source You can also run Redis MCP from source, which may be useful if you want to contribute to the project. Clone Redis MCP from the [Github repository](https://github.com/redis/mcp-redis) using the following command: ```bash git clone https://github.com/redis/mcp-redis.git ``` You will also need the [`uv`](https://github.com/astral-sh/uv) packaging tool to set up the server. See the `uv` [installation instructions](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) for more information. When you have installed `uv`, go to the `mcp-redis` folder that you cloned and enter the following commands to initialize the MCP server code: ```bash cd mcp-redis 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 ``` ## Install using Docker You can use the [`mcp/redis`](https://hub.docker.com/r/mcp/redis) image to run Redis MCP with [Docker](https://www.docker.com/). Alternatively, use the following command to build the Docker image with the `Dockerfile` in the `mcp/redis` folder: ``` docker build -t mcp-redis . ``` ## Configuration The default settings for MCP assume a Redis server is running on the local machine, with the default port and no security arrangements. You can use environment variables to change these settings (see [Environment variables](#environment-variables) below for the full list). For example, for a `bash` shell, use ```bash export REDIS_USERNAME="my_username" ``` from the command line or the `.bashrc` file to set the username you want to connect with. Alternatively, you can use a `.env` file in your project folder to set the environment variables as key-value pairs, one per line: ``` REDIS_HOST=your_redis_host REDIS_PORT=6379 . . ``` See the [`.env.example` file](https://github.com/redis/mcp-redis/blob/main/.env.example) in the repository for the full list of variables and their default values. You can also set the configuration using command-line arguments, which may be useful if you only want to change a few settings from the defaults (see [Command line options](#command-line-options) below for the full list of options). ```bash # 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 ``` > [!NOTE] > The command-line options take precedence over the environment variables. ### Environment variables The full set of environment variables is shown in the table below. The `REDIS_ENTRAID_XXX` variables (used for EntraID authentication to Azure Managed Redis) are described in the [EntraID authentication](#entraid-authentication) section. | Name | Description | Default Value | |----------------------|-----------------------------|---------------| | `REDIS_HOST` | Redis IP or hostname | `"127.0.0.1"` | | `REDIS_PORT` | Redis port | `6379` | | `REDIS_DB` | Database | 0 | | `REDIS_USERNAME` | Database username | `"default"` | | `REDIS_PWD` | Database password | "" | | `REDIS_SSL` | Enables or disables SSL/TLS | `False` | | `REDIS_CA_PATH` | CA certificate for verifying server | None | | `REDIS_SSL_KEYFILE` | Client's private key file for client authentication | None | | `REDIS_SSL_CERTFILE` | Client's certificate file for client authentication | None | | `REDIS_CERT_REQS` | Whether the client should verify the server's certificate | `"required"` | | `REDIS_CA_CERTS` | Path to the trusted CA certificates file | None | | `REDIS_CLUSTER_MODE` | Enable Redis Cluster mode | `False` | | `REDIS_ENTRAID_AUTH_FLOW` | Authentication flow type | None (EntraID disabled) | | `REDIS_ENTRAID_CLIENT_ID` | Service Principal client ID | None | | `REDIS_ENTRAID_CLIENT_SECRET` | Service Principal client secret | None | | `REDIS_ENTRAID_TENANT_ID` | Azure tenant ID | None | | `REDIS_ENTRAID_IDENTITY_TYPE` | Managed identity type | `"system_assigned"` | | `REDIS_ENTRAID_USER_ASSIGNED_CLIENT_ID` | User-assigned managed identity client ID | None | | `REDIS_ENTRAID_SCOPES` | OAuth scopes for Default Azure Credential | `"https://redis.azure.com/.default"` | | `REDIS_ENTRAID_RESOURCE` | Azure Redis resource identifier | `"https://redis.azure.com/"` | ### Command line options The full set of command line options is shown in the table below: | Name | Description | Default Value | |----------------------|-----------------|---------------| | `--url` | Redis URL (`redis://user:pass@host:port/db`) | | | `--host` | Redis IP or hostname | `"127.0.0.1"` | | `--port` | Redis port | `6379` | | `--db` | Database | 0 | | `--username` | Database username | `"default"` | | `--password` | Database password | | | `--ssl` | Enables or disables SSL/TLS | `False` | | `--ssl-ca-path` | CA certificate for verifying server | None | | `--ssl-keyfile` | Client's private key file for client authentication | | | `--ssl-certfile` | Client's certificate file for client authentication | | | `--ssl-cert-reqs` | Whether the client should verify the server's certificate | `"required"` | | `--ssl-ca-certs` | Path to the trusted CA certificates file | | | `--cluster-mode` | Enable Redis Cluster mode | `False` | ### EntraID authentication The Redis MCP Server supports EntraID (Azure Active Directory) authentication for Azure Managed Redis, enabling OAuth-based authentication with automatic token management. This uses redis-py's [redis-entra-id](https://redis.io/docs/latest/develop/clients/redis-py/amr) library to offer: - **Automatic token renewal** - Refreshes tokens in the background with no manual intervention - **Graceful fallback** - Falls back to standard Redis authentication when EntraID is not configured - **Multiple auth flows** - Supports Service Principal, Managed Identity, and Default Azure Credential - **Enterprise capabilities** - Designed for Azure Managed Redis with centralized identity management Use the `REDIS_ENTRAID_XXX` environment variables to configure EntraID authentication. Some common configurations are: - **Local development with Azure CLI**: ```bash # 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 ``` - **Production usage with Service Principal**: ```bash 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 ``` - **Azure-hosted application with Managed Identity**: ```bash 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 ``` ## Redis Cloud MCP A separate MCP server is available for [Redis Cloud](https://redis.io/docs/latest/operate/rc). This has features specific to Redis Cloud, including subscription management and billing details. For example, you can use questions and instructions like the following: - "Create a new Redis database in AWS" - "What are my current subscriptions?" - "Help me choose the right Redis database for my e-commerce application" > [!NOTE] > By itself, the Redis Cloud MCP server only provides admin > features and does not let you interact > with Redis databases. You can still use the main MCP server for interaction > with a Cloud database, but you must install it separately. You will need [Node.js](https://nodejs.org/en) installed to run Redis Cloud MCP. Clone the GitHub repository using the following command: ```bash git clone https://github.com/redis/mcp-redis-cloud.git ``` Go into the `mcp-redis-cloud` folder and install the dependencies: ```bash npm run build ``` The server is now ready for use. You can also deploy Redis Cloud MCP using Docker. Build the image using the `Dockerfile` in the repository folder with the following command: ```bash docker build -t mcp/redis-cloud . ``` ## Next steps When you have installed the server, you will need a MCP client to connect to it and use its services. See [Configure client apps](https://redis.io/docs/latest/integrate/redis-mcp/client-conf) for more information.