# Redis MCP Server

A Model Context Protocol (MCP) server for Redis. Connect to any Redis instance and execute queries through AI assistants.

## Features

- 🔌 **Connect to any Redis instance** - Local or remote, with authentication and TLS support
- 🛠️ **30+ Built-in Tools** - Complete Redis operations including strings, hashes, lists, sets, sorted sets
- 🔒 **Command Blacklist** - Block dangerous commands (FLUSHALL, SHUTDOWN, etc.)
- 💾 **Connection Management** - Save and switch between multiple Redis connections
- 🌐 **Web UI** - Browser-based management interface
- 🔐 **Password Encryption** - AES-256-GCM encryption for saved passwords

## Screenshots

![Connection Management](assets/1.png)

![Redis Explorer](assets/2.png)

![Command Blacklist](assets/3.png)

![Query Console](assets/4.png)

![Server Info](assets/5.png)

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/minivv/redis-mcp-server.git
cd redis-mcp-server
```

### 2. Install dependencies and build

```bash
npm install
npm run build
```

### 3. Configure MCP Client

Add to your Claude Desktop, Cursor, or other MCP client configuration:

```json
{
  "mcpServers": {
    "redis-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/your/path/to/redis-mcp-server/build/index.js"
      ],
      "env": {
        "MCP_OPEN_BROWSER": "false",
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "REDIS_PASSWORD": "",
        "REDIS_DB": "0"
      }
    }
  }
}
```

> ⚠️ **注意**: 请将 `args` 中的路径 `/your/path/to/redis-mcp-server/build/index.js` 改为你本机实际的项目路径，例如 `/Users/yourname/projects/redis-mcp-server/build/index.js`。

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `REDIS_HOST` | `localhost` | Redis host |
| `REDIS_PORT` | `6379` | Redis port |
| `REDIS_PASSWORD` | - | Redis password |
| `REDIS_DB` | `0` | Database number (0-15) |
| `REDIS_USERNAME` | - | Redis username (for ACL) |
| `REDIS_TLS` | `false` | Use TLS connection |
| `MCP_WEB_PORT` | `3457` | Web UI port |
| `MCP_OPEN_BROWSER` | `true` | Auto-open browser on start |

## Available Tools

### Connection Management

| Tool | Description |
|------|-------------|
| `get_connection_info` | Get current Redis connection details |
| `list_saved_connections` | List all saved Redis connections |
| `save_connection` | Save a Redis connection configuration |
| `use_connection` | Switch to a saved Redis connection |
| `delete_connection` | Delete a saved Redis connection |
| `test_connection` | Test a Redis connection by sending PING |

### Query Execution

| Tool | Description |
|------|-------------|
| `execute_command` | Execute any Redis command (with blacklist check) |
| `run_redis_query` | Execute read-only Redis commands only |

### Key Operations

| Tool | Description |
|------|-------------|
| `list_keys` | List keys matching a pattern |
| `get_key_info` | Get detailed information about a key |
| `delete_key` | Delete one or more keys |
| `rename_key` | Rename a key |
| `set_ttl` | Set expiration time for a key |
| `get_ttl` | Get remaining TTL for a key |

### String Operations

| Tool | Description |
|------|-------------|
| `get_string` | Get the value of a string key |
| `set_string` | Set the value of a string key (with optional TTL) |

### Hash Operations

| Tool | Description |
|------|-------------|
| `get_hash` | Get all or specific fields of a hash |
| `set_hash` | Set fields in a hash |

### List Operations

| Tool | Description |
|------|-------------|
| `get_list` | Get elements from a list by range |
| `push_list` | Push elements to a list (left or right) |

### Set Operations

| Tool | Description |
|------|-------------|
| `get_set` | Get all members of a set |
| `add_set` | Add members to a set |

### Sorted Set Operations

| Tool | Description |
|------|-------------|
| `get_sorted_set` | Get members from a sorted set |
| `add_sorted_set` | Add members with scores to a sorted set |

### Database Operations

| Tool | Description |
|------|-------------|
| `select_database` | Select a Redis database (0-15) |
| `get_database_size` | Get the number of keys in the current database |
| `get_server_info` | Get Redis server information |

### Blacklist Management

| Tool | Description |
|------|-------------|
| `get_command_blacklist` | Get the current command blacklist configuration |
| `update_command_blacklist` | Update the command blacklist configuration |
| `reset_command_blacklist` | Reset command blacklist to default patterns |

## Command Blacklist

By default, the following commands are blocked:

- `FLUSHALL` - Flush all databases
- `FLUSHDB` - Flush current database
- `SHUTDOWN` - Shutdown Redis server
- `DEBUG SEGFAULT` - Debug segfault
- `CONFIG SET` - Change Redis config
- `CONFIG REWRITE` - Rewrite Redis config
- `SLAVEOF` - Set replication
- `REPLICAOF` - Set replication
- `CLUSTER *` - Cluster commands
- `RESET` - Reset connection

You can customize the blacklist through the Web UI or using the `update_command_blacklist` tool.

## Web UI

The Web UI provides a browser-based interface for:

- Managing Redis connections
- Testing connections
- Managing the command blacklist
- Testing commands against the blacklist

Access it at `http://localhost:3457` (default port).

## Configuration Storage

All configuration is stored in `~/.redis-mcp/`:

- `connections.json` - Saved connections
- `command-blacklist.json` - Command blacklist rules
- `.key` - Encryption key for passwords

## Security

- Passwords are encrypted using AES-256-GCM
- Dangerous commands are blocked by default
- The encryption key is stored with restricted permissions (0600)

## License

MIT