MCP Redis Server

A MCP Redis server with data operations, permission control and operation logs.

Features

✅ Redis data operations (GET, SET, UPDATE, DELETE)
✅ Key management (CREATE, DROP, EXISTS, INFO)
✅ Dynamic tool list based on permissions
✅ Operation logging
✅ Connection management
✅ Auto-reconnection mechanism
✅ Health checks
✅ Error handling and recovery

Installation

Global Installation (Recommended)

npm install -g @liangshanli/mcp-server-redis

Local Installation

npm install @liangshanli/mcp-server-redis

From Source

git clone https://github.com/liliangshan/mcp-server-redis.git
cd mcp-server-redis
npm install

Configuration

Set environment variables:

export HOST=localhost
export PORT=6379
export PASSWORD=your_password
export ALLOW_INSERT=true
export ALLOW_UPDATE=true
export ALLOW_DELETE=true
export ALLOW_CREATE=true
export ALLOW_DROP=true

Usage

1. Direct Run (Global Installation)

mcp-server-redis

2. Using npx (Recommended)

npx @liangshanli/mcp-server-redis

3. Direct Start (Source Installation)

npm start

4. Managed Start (Recommended for Production)

npm run start-managed

Managed start provides:

Auto-restart (up to 10 times)
Error recovery
Process management
Logging

5. Development Mode

npm run dev

Editor Integration

Cursor Editor Configuration

Create .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "redis": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-redis"],
      "env": {
        "HOST": "your_host",
        "PORT": "6379",
        "PASSWORD": "your_password",
        "ALLOW_INSERT": "true",
        "ALLOW_UPDATE": "true",
        "ALLOW_DELETE": "true",
        "ALLOW_CREATE": "true",
        "ALLOW_DROP": "true"
      }
    }
  }
}

VS Code Configuration

Install the MCP extension for VS Code
Create .vscode/settings.json file:

{
  "mcp.servers": {
    "redis": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-redis"],
      "env": {
        "HOST": "your_host",
        "PORT": "6379",
        "PASSWORD": "your_password",
        "ALLOW_INSERT": "true",
        "ALLOW_UPDATE": "true",
        "ALLOW_DELETE": "true",
        "ALLOW_CREATE": "true",
        "ALLOW_DROP": "true"
      }
    }
  }
}

As MCP Server

The server communicates with MCP clients via stdin/stdout after startup:

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}

Available Tools

get_data: Get data by key

   {
     "jsonrpc": "2.0",
     "id": 2,
     "method": "tools/call",
     "params": {
       "name": "get_data",
       "arguments": {
         "key": "user:123"
       }
     }
   }

set_data: Set/insert data for a key

   {
     "jsonrpc": "2.0",
     "id": 3,
     "method": "tools/call",
     "params": {
       "name": "set_data",
       "arguments": {
         "key": "user:123",
         "value": "John Doe",
         "ttl": 3600
       }
     }
   }

list_keys: List Redis keys with pattern matching

   {
     "jsonrpc": "2.0",
     "id": 4,
     "method": "tools/call",
     "params": {
       "name": "list_keys",
       "arguments": {
         "pattern": "user:*",
         "limit": 10
       }
     }
   }

Dynamic Tool List

The server dynamically shows/hides tools based on environment variables:

Read-Only Tools (Always Available)

get_data - Get data by key
list_keys - List keys with pattern matching
exists_key - Check if key exists
get_key_info - Get key information
get_redis_info - Get Redis server information
get_database_stats - Get database statistics
get_memory_info - Get memory usage information
test_connection - Test Redis connection
get_operation_logs - Get operation logs
check_permissions - Check current permissions
set_ttl - Set time to live for a key
remove_ttl - Remove time to live from a key

Conditional Tools (Based on Permissions)

set_data - Requires ALLOW_INSERT=true
update_data - Requires ALLOW_UPDATE=true
delete_data - Requires ALLOW_DELETE=true
create_key - Requires ALLOW_CREATE=true
drop_key - Requires ALLOW_DROP=true
rename_key - Requires ALLOW_CREATE=true AND ALLOW_DROP=true

Connection Management Features

Auto-creation: Automatically creates Redis connection on notifications/initialized
Health checks: Checks connection status every 5 minutes
Auto-reconnection: Automatically reconnects when connection fails
Connection reuse: Uses connection pool for better performance
Graceful shutdown: Properly closes connections when server shuts down

Logging

Log file location: ./logs/mcp-redis.log

Logged content:

All requests and responses
Redis operation records
Error messages
Connection status changes

Error Handling

Individual request errors don't affect the entire server
Connection errors are automatically recovered
Process exceptions are automatically restarted (managed mode)

Environment Variables

| Variable | Default | Description | |---------|---------|-------------| | HOST | localhost | Redis host address | | PORT | 6379 | Redis port | | PASSWORD | | Redis password | | ALLOW_INSERT | true | Whether to allow insert operations. Set to 'false' to disable | | ALLOW_UPDATE | true | Whether to allow update operations. Set to 'false' to disable | | ALLOW_DELETE | true | Whether to allow delete operations. Set to 'false' to disable | | ALLOW_CREATE | true | Whether to allow create key operations. Set to 'false' to disable | | ALLOW_DROP | true | Whether to allow drop/delete key operations. Set to 'false' to disable | | MCP_LOG_DIR | ./logs | Log directory | | MCP_LOG_FILE | mcp-redis.log | Log filename |

Development

Project Structure

mcp-server-redis/
├── src/
│   ├── server-final.js        # Main server file
│   └── utils/                 # Utility modules
├── bin/
│   └── cli.js                 # CLI entry point
├── start-server.js            # Managed startup script
├── package.json
└── README.md

Testing

npm test

Quick Start

1. Install Package

npm install -g @liangshanli/mcp-server-redis

2. Configure Environment Variables

export HOST=localhost
export PORT=6379
export PASSWORD=your_password
export ALLOW_INSERT=true
export ALLOW_UPDATE=true
export ALLOW_DELETE=true
export ALLOW_CREATE=true
export ALLOW_DROP=true

Permission Control Examples: ```bash

Default: Enable all operations

export ALLOW_INSERT=true export ALLOW_UPDATE=true export ALLOW_DELETE=true export ALLOW_CREATE=true export ALLOW_DROP=true

Read-only mode (safe mode)

export ALLOW_INSERT=false export ALLOW_UPDATE=false export ALLOW_DELETE=false export ALLOW_CREATE=false export ALLOW_DROP=false

Allow insert and update, but disable delete operations

export ALLOW_INSERT=true export ALLOW_UPDATE=true export ALLOW_DELETE=false export ALLOW_CREATE=true export ALLOW_DROP=false

Allow everything except DROP operations

export ALLOW_INSERT=true export ALLOW_UPDATE=true export ALLOW_DELETE=true export ALLOW_CREATE=true export ALLOW_DROP=false ```

3. Run Server

mcp-server-redis

License

MIT

mcp-server-redis