{ "schema_version": 2, "id": "integrate/redis-mcp/install", "title": "Install", "url": "https://redis.io/docs/latest/integrate/redis-mcp/install/", "summary": "Install and configure the Redis MCP server.", "tags": [ "docs", "integrate", "rs" ], "last_updated": "2026-09-17T14:55:03+01:00", "page_type": "content", "content_hash": "b54a40ef2c719eaa084869704a746471dada6cf94d355cb6a81999ab1dcee798", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "The MCP server runs separately from Redis, so you will need a\nRedis server for it to connect to. See [Redis Cloud](https://redis.io/docs/latest/operate/rc)\nor [Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack) to learn\nhow to get a test server active within minutes.\n\nWhen you have a Redis server available, use the instructions below to install and\nconfigure the Redis MCP server." }, { "id": "quick-start-with-pypi", "title": "Quick Start with PyPI", "role": "content", "text": "The easiest way to use the Redis MCP Server is with\n[`uvx`](https://docs.astral.sh/uv/guides/tools/),\nwhich lets you run it from its [PyPI package](https://pypi.org/project/redis-mcp-server/)\n(see the `uv`\n[installation instructions](https://github.com/astral-sh/uv?tab=readme-ov-file#installation)\nfor more information.)\n\n[code example]" }, { "id": "run-from-github", "title": "Run from GitHub", "role": "content", "text": "Running from [PyPI](#quick-start-with-pypi)\nis the recommended way to use the Redis MCP server, but\nyou can also run it from a GitHub branch or a tagged release with `uvx`:\n\n[code example]" }, { "id": "install-the-server-from-source", "title": "Install the server from source", "role": "setup", "text": "You can also run Redis MCP from source, which may be useful if you want to\ncontribute to the project.\n\nClone Redis MCP from the\n[Github repository](https://github.com/redis/mcp-redis) using the following\ncommand:\n\n[code example]\n\nYou will also need the [`uv`](https://github.com/astral-sh/uv) packaging\ntool to set up the server. See the `uv`\n[installation instructions](https://github.com/astral-sh/uv?tab=readme-ov-file#installation)\nfor more information.\n\nWhen you have installed `uv`, go to the `mcp-redis` folder that you cloned and\nenter the following commands to initialize the MCP server code:\n\n[code example]" }, { "id": "install-using-docker", "title": "Install using Docker", "role": "setup", "text": "You can use the [`mcp/redis`](https://hub.docker.com/r/mcp/redis)\nimage to run Redis MCP with [Docker](https://www.docker.com/).\nAlternatively, use the following\ncommand to build the Docker image with the `Dockerfile` in the\n`mcp/redis` folder:\n\n[code example]" }, { "id": "configuration", "title": "Configuration", "role": "configuration", "text": "The default settings for MCP assume a Redis server is running on the\nlocal machine, with the default port and no security arrangements.\nYou can use environment variables to change these settings\n(see [Environment variables](#environment-variables) below for the full list).\nFor example, for a `bash` shell, use\n\n[code example]\n\nfrom the command line or the `.bashrc` file to set the username you want\nto connect with.\n\nAlternatively, you can use a `.env` file in your project folder to set the\nenvironment variables as key-value pairs, one per line:\n\n[code example]\n\nSee the [`.env.example` file](https://github.com/redis/mcp-redis/blob/main/.env.example)\nin the repository for the full list of variables and their default values.\n\nYou can also set the configuration using command-line arguments, which\nmay be useful if you only want to change a few settings from the defaults\n(see [Command line options](#command-line-options) below for the full list\nof options).\n\n[code example]\n\n> [!NOTE]\n> The command-line options take precedence over the environment variables." }, { "id": "environment-variables", "title": "Environment variables", "role": "content", "text": "The full set of environment variables is shown in the table below. The\n`REDIS_ENTRAID_XXX` variables (used for EntraID authentication to\nAzure Managed Redis) are described in the\n[EntraID authentication](#entraid-authentication) section. \n\n| Name | Description | Default Value |\n|----------------------|-----------------------------|---------------|\n| `REDIS_HOST` | Redis IP or hostname | `\"127.0.0.1\"` |\n| `REDIS_PORT` | Redis port | `6379` |\n| `REDIS_DB` | Database | 0 |\n| `REDIS_USERNAME` | Database username | `\"default\"` |\n| `REDIS_PWD` | Database password | \"\" |\n| `REDIS_SSL` | Enables or disables SSL/TLS | `False` |\n| `REDIS_CA_PATH` | CA certificate for verifying server | None |\n| `REDIS_SSL_KEYFILE` | Client's private key file for client authentication | None |\n| `REDIS_SSL_CERTFILE` | Client's certificate file for client authentication | None |\n| `REDIS_CERT_REQS` | Whether the client should verify the server's certificate | `\"required\"` |\n| `REDIS_CA_CERTS` | Path to the trusted CA certificates file | None |\n| `REDIS_CLUSTER_MODE` | Enable Redis Cluster mode | `False` |\n| `REDIS_ENTRAID_AUTH_FLOW` | Authentication flow type | None (EntraID disabled) |\n| `REDIS_ENTRAID_CLIENT_ID` | Service Principal client ID | None |\n| `REDIS_ENTRAID_CLIENT_SECRET` | Service Principal client secret | None |\n| `REDIS_ENTRAID_TENANT_ID` | Azure tenant ID | None |\n| `REDIS_ENTRAID_IDENTITY_TYPE` | Managed identity type | `\"system_assigned\"` |\n| `REDIS_ENTRAID_USER_ASSIGNED_CLIENT_ID` | User-assigned managed identity client ID | None |\n| `REDIS_ENTRAID_SCOPES` | OAuth scopes for Default Azure Credential | `\"https://redis.azure.com/.default\"` |\n| `REDIS_ENTRAID_RESOURCE` | Azure Redis resource identifier | `\"https://redis.azure.com/\"` |" }, { "id": "command-line-options", "title": "Command line options", "role": "syntax", "text": "The full set of command line options is shown in the table below:\n\n| Name | Description | Default Value |\n|----------------------|-----------------|---------------|\n| `--url` | Redis URL (`redis://user:pass@host:port/db`) | |\n| `--host` | Redis IP or hostname | `\"127.0.0.1\"` |\n| `--port` | Redis port | `6379` |\n| `--db` | Database | 0 |\n| `--username` | Database username | `\"default\"` |\n| `--password` | Database password | |\n| `--ssl` | Enables or disables SSL/TLS | `False` |\n| `--ssl-ca-path` | CA certificate for verifying server | None |\n| `--ssl-keyfile` | Client's private key file for client authentication | |\n| `--ssl-certfile` | Client's certificate file for client authentication | |\n| `--ssl-cert-reqs` | Whether the client should verify the server's certificate | `\"required\"` |\n| `--ssl-ca-certs` | Path to the trusted CA certificates file | |\n| `--cluster-mode` | Enable Redis Cluster mode | `False` |" }, { "id": "entraid-authentication", "title": "EntraID authentication", "role": "content", "text": "The Redis MCP Server supports EntraID (Azure Active Directory) authentication\nfor 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:\n\n- **Automatic token renewal** - Refreshes tokens in the background with no manual intervention\n- **Graceful fallback** - Falls back to standard Redis authentication when EntraID is not configured\n- **Multiple auth flows** - Supports Service Principal, Managed Identity, and Default Azure Credential\n- **Enterprise capabilities** - Designed for Azure Managed Redis with centralized identity management\n\nUse the `REDIS_ENTRAID_XXX` environment variables to configure EntraID authentication.\nSome common configurations are:\n\n- **Local development with Azure CLI**:\n [code example]\n- **Production usage with Service Principal**:\n\n [code example]\n- **Azure-hosted application with Managed Identity**:\n\n [code example]" }, { "id": "redis-cloud-mcp", "title": "Redis Cloud MCP", "role": "content", "text": "A separate MCP server is available for\n[Redis Cloud](https://redis.io/docs/latest/operate/rc). This has features\nspecific to Redis Cloud, including subscription management and\nbilling details. For example, you can use questions and instructions\nlike the following:\n\n- \"Create a new Redis database in AWS\"\n- \"What are my current subscriptions?\"\n- \"Help me choose the right Redis database for my e-commerce application\"\n\n> [!NOTE]\n> By itself, the Redis Cloud MCP server only provides admin\n> features and does not let you interact\n> with Redis databases. You can still use the main MCP server for interaction\n> with a Cloud database, but you must install it separately.\n\nYou will need [Node.js](https://nodejs.org/en) installed to run Redis Cloud MCP.\nClone the GitHub repository using the following command:\n\n[code example]\n\nGo into the `mcp-redis-cloud` folder and install the dependencies:\n\n[code example]\n\nThe server is now ready for use.\n\nYou can also deploy Redis Cloud MCP using Docker. Build the image\nusing the `Dockerfile` in the repository folder with the following\ncommand:\n\n[code example]" }, { "id": "next-steps", "title": "Next steps", "role": "content", "text": "When you have installed the server, you will need a MCP client to\nconnect to it and use its services. See\n[Configure client apps](https://redis.io/docs/latest/integrate/redis-mcp/client-conf)\nfor more information." } ], "examples": [ { "id": "quick-start-with-pypi-ex0", "language": "bash", "code": "# Run with Redis URI\nuvx --from redis-mcp-server@latest redis-mcp-server --url redis://localhost:6379/0\n\n# Run with Redis URI and SSL \nuvx --from redis-mcp-server@latest redis-mcp-server --url \"rediss://:@:?ssl_cert_reqs=required&ssl_ca_certs=\"\n\n# Run with individual parameters\nuvx --from redis-mcp-server@latest redis-mcp-server --host localhost --port 6379 --password mypassword\n\n# See all options\nuvx --from redis-mcp-server@latest redis-mcp-server --help", "section_id": "quick-start-with-pypi" }, { "id": "run-from-github-ex0", "language": "bash", "code": "# Run with Redis URI\nuvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url redis://localhost:6379/0\n\n# Run with Redis URI and SSL \nuvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url \"rediss://:@:?ssl_cert_reqs=required&ssl_ca_certs=\"\n\n# Run with individual parameters\nuvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --host localhost --port 6379 --password mypassword\n\n# See all options\nuvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --help", "section_id": "run-from-github" }, { "id": "install-the-server-from-source-ex0", "language": "bash", "code": "git clone https://github.com/redis/mcp-redis.git", "section_id": "install-the-server-from-source" }, { "id": "install-the-server-from-source-ex1", "language": "bash", "code": "cd mcp-redis\n\nuv venv\nsource .venv/bin/activate\nuv sync\n\n# Run with CLI interface\nuv run redis-mcp-server --help\n\n# Or run the main file directly (uses environment variables)\nuv run src/main.py", "section_id": "install-the-server-from-source" }, { "id": "install-using-docker-ex0", "language": "plaintext", "code": "docker build -t mcp-redis .", "section_id": "install-using-docker" }, { "id": "configuration-ex0", "language": "bash", "code": "export REDIS_USERNAME=\"my_username\"", "section_id": "configuration" }, { "id": "configuration-ex1", "language": "plaintext", "code": "REDIS_HOST=your_redis_host\nREDIS_PORT=6379\n .\n .", "section_id": "configuration" }, { "id": "configuration-ex2", "language": "bash", "code": "# Basic Redis connection\nuvx --from redis-mcp-server@latest redis-mcp-server \\\n --host localhost \\\n --port 6379 \\\n --password mypassword\n\n# Using Redis URI (simpler)\nuvx --from redis-mcp-server@latest redis-mcp-server \\\n --url redis://user:pass@localhost:6379/0\n\n# SSL connection\nuvx --from redis-mcp-server@latest redis-mcp-server \\\n --url rediss://user:pass@redis.example.com:6379/0\n\n# See all available options\nuvx --from redis-mcp-server@latest redis-mcp-server --help", "section_id": "configuration" }, { "id": "entraid-authentication-ex0", "language": "bash", "code": "# Login with Azure CLI\n az login\n\n # Configure MCP server\n export REDIS_ENTRAID_AUTH_FLOW=default_credential\n export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379", "section_id": "entraid-authentication" }, { "id": "entraid-authentication-ex1", "language": "bash", "code": "export REDIS_ENTRAID_AUTH_FLOW=service_principal\n export REDIS_ENTRAID_CLIENT_ID=your-app-client-id\n export REDIS_ENTRAID_CLIENT_SECRET=your-app-secret\n export REDIS_ENTRAID_TENANT_ID=your-tenant-id\n export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379", "section_id": "entraid-authentication" }, { "id": "entraid-authentication-ex2", "language": "bash", "code": "export REDIS_ENTRAID_AUTH_FLOW=managed_identity\n export REDIS_ENTRAID_IDENTITY_TYPE=system_assigned\n export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379", "section_id": "entraid-authentication" }, { "id": "redis-cloud-mcp-ex0", "language": "bash", "code": "git clone https://github.com/redis/mcp-redis-cloud.git", "section_id": "redis-cloud-mcp" }, { "id": "redis-cloud-mcp-ex1", "language": "bash", "code": "npm run build", "section_id": "redis-cloud-mcp" }, { "id": "redis-cloud-mcp-ex2", "language": "bash", "code": "docker build -t mcp/redis-cloud .", "section_id": "redis-cloud-mcp" } ] }