diff --git a/content/integrate/redis-mcp/_index.md b/content/integrate/redis-mcp/_index.md new file mode 100644 index 0000000000..705ca4c937 --- /dev/null +++ b/content/integrate/redis-mcp/_index.md @@ -0,0 +1,40 @@ +--- +Title: Redis MCP +alwaysopen: false +categories: +- docs +- integrate +- rs +description: Access a Redis server using any MCP client. +group: service +hideListLinks: false +linkTitle: Redis MCP +summary: Redis MCP server lets MCP clients access the features of Redis. +type: integration +weight: 1 +--- + +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) +is a standard that lets AI agents access data and perform actions. Using MCP, +your server can publish a set of commands that are usable by any MCP-compatible +client app (such as [Claude Desktop](https://claude.ai/download) or +[VS Code](https://code.visualstudio.com/)). These commands can retrieve +whatever data you wish to provide and you can also let the agent make +changes to the data. For example, you could publish a feed of news items that +an agent can use in its responses, and also let the agent add the user's +comments to those items. + +Redis MCP is a general-purpose implementation that lets agents read, write, and +query data in Redis and also has some basic commands to manage the Redis +server. With this enabled, you can use an LLM client as a very high-level +interface to Redis. Add, query, and analyze any Redis data set directly from +an LLM chat using instructions and questions like the following: + +- "Store the entire conversation in the 'recent_chats' stream" +- "Cache this item" +- "How many keys does my database have?" +- "What is user:1's email?" + +See the other pages in this section to learn how to set up and use Redis MCP. +See also the [GitHub repository](https://github.com/redis/mcp-redis) for +the latest changes. diff --git a/content/integrate/redis-mcp/client-conf.md b/content/integrate/redis-mcp/client-conf.md new file mode 100644 index 0000000000..99fa4d6602 --- /dev/null +++ b/content/integrate/redis-mcp/client-conf.md @@ -0,0 +1,175 @@ +--- +Title: Configure client apps +alwaysopen: false +categories: +- docs +- integrate +- rs +summary: Access a Redis server using any MCP client. +group: service +linkTitle: Configure client apps +description: Configure client apps to use the Redis MCP server. +type: integration +weight: 20 +--- + +When you have [installed]({{< relref "/integrate/redis-mcp/install" >}}) +the Redis MCP server, you must also configure your client app to use it. +The sections below describe the ways you can do this. + +## Smithery + +[Smithery](https://smithery.ai/) provides a searchable repository of scripts +that add configurations for many MCP services to client apps. +The easiest way to configure your client is to use the +[Smithery tool for Redis MCP](https://smithery.ai/server/@redis/mcp-redis). + +When you select your client from the **Install** bar on the Redis MCP page, +you will see a command line that you can copy and paste into a terminal. +Running this command will configure your client app to use Redis MCP. (Note +that you must have [Node.js](https://nodejs.org/en) installed to run +the Smithery scripts.) For example, the command line for +[Claude Desktop](https://claude.ai/download) is + +```bash +npx -y @smithery/cli@latest install @redis/mcp-redis --client claude +``` + +The script will prompt you for the information required to connect to +your Redis database. + +## Manual configuration + +You can also add the configuration for Redis MCP to your client app +manually. The exact method varies from client to client but the +basic approach is similar in each case. The pages listed below +give the general configuration details for some common MCP client tools: + +- [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) +- [GitHub Copilot for VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) +- [OpenAI](https://openai.github.io/openai-agents-python/mcp/) + +### Local servers + +For a locally-running MCP server, you need to edit the configuration +file to add the command that launches the server, along with its +arguments. For example, with Claude Desktop, you can locate the +file by selecting **Settings** from the menu, then selecting the +**Developer** tab, and then clicking the **Edit Config** button. +Open this JSON file and add your settings as +shown below: + +```json +{ + "mcpServers": { + . + . + "redis-mcp-server": { + "type": "stdio", + "command": "uvx", + "args": [ + "--from", "git+https://github.com/redis/mcp-redis.git", + "redis-mcp-server", + "--url", "redis://localhost:6379/0" + ] + } + } + . + . + } +``` + +You can find the path to the `uv` command using `which uv`, or +the equivalent. You can also optionally set the environment for +the command shell here in the `env` section: + +```json +"redis": { + "type": "stdio", + "command": "uvx", + "args": [ + "--from", "git+https://github.com/redis/mcp-redis.git", + "redis-mcp-server", + "--url", "redis://localhost:6379/0" + ], + "env": { + "REDIS_HOST": "", + "REDIS_PORT": "", + "REDIS_PWD": "", + "REDIS_SSL": True|False, + "REDIS_CA_PATH": "", + "REDIS_CLUSTER_MODE": True|False + } +} +``` + +If you are using +[Docker]({{< relref "/integrate/redis-mcp/install#install-using-docker" >}}) +to deploy the server, change the `command` and `args` sections of the +configuration as shown below: + +```json +"redis": { + "command": "docker", + "args": ["run", + "--rm", + "--name", + "redis-mcp-server", + "-i", + "-e", "REDIS_HOST=", + "-e", "REDIS_PORT=", + "-e", "REDIS_USERNAME=", + "-e", "REDIS_PWD=", + "mcp-redis"] +} +``` + +## Redis Cloud MCP + +If you are using +[Redis Cloud MCP]({{< relref "/integrate/redis-mcp/install#redis-cloud-mcp" >}}), +the configuration is similar to [basic MCP](#manual-configuration), but with a +few differences. Set the client to run the server using the `node` command, as shown +in the example for Claude Desktop below: + +```json +{ + "mcpServers": { + "mcp-redis-cloud": { + "command": "node", + "args": ["--experimental-fetch", "/dist/index.js"], + "env": { + "API_KEY": "", + "SECRET_KEY": "" + } + } + } +} +``` + +Here, the environment includes the Redis Cloud API key and API secret key +(see [Redis Cloud REST API]({{< relref "/operate/rc/api" >}}) for more +information). + +If you are deploying Redis Cloud MCP with Docker, use a configuration like +the following to launch the server with the `docker` command: + +```json +{ + "mcpServers": { + "redis-cloud": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "API_KEY=", + "-e", + "SECRET_KEY=", + "mcp/redis-cloud" + ] + } + } +} +``` diff --git a/content/integrate/redis-mcp/install.md b/content/integrate/redis-mcp/install.md new file mode 100644 index 0000000000..720c9e9e64 --- /dev/null +++ b/content/integrate/redis-mcp/install.md @@ -0,0 +1,203 @@ +--- +Title: Install +alwaysopen: false +categories: +- docs +- integrate +- rs +summary: Access a Redis server using any MCP client. +group: service +linkTitle: Install the server +description: Install and configure the Redis MCP server. +type: integration +weight: 10 +--- + +The MCP server runs separately from Redis, so you will need a +Redis server for it to connect to. See [Redis Cloud]({{< relref "/operate/rc" >}}) +or [Redis Open Source]({{< relref "/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 uvx + +The easiest way to use the Redis MCP Server is with [`uvx`](https://docs.astral.sh/uv/guides/tools/), +which lets you run it directly from a GitHub branch or a tagged release (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 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: + +```bash +# Basic Redis connection +uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server \ + --host localhost \ + --port 6379 \ + --password mypassword + +# Using Redis URI (simpler) +uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server \ + --url redis://user:pass@localhost:6379/0 + +# SSL connection +uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server \ + --url rediss://user:pass@redis.example.com:6379/0 + +# See all available options +uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --help +``` + +### Environment variables + +The full set of environment variables is shown in the table below: + +| 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` | +| `MCP_TRANSPORT` | Use the `stdio` or `sse` transport | `stdio` | + +## Redis Cloud MCP + +A separate version of the MCP server is available for +[Redis Cloud]({{< relref "/operate/rc" >}}). This has the same main +functionality as the basic MCP server but also has some 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" + +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]({{< relref "/integrate/redis-mcp/client-conf" >}}) +for more information.