liliangshan/mcp-server-redis

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

1. 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

1. Install the MCP extension for VS Code
2. 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

1. get_data: Get data by key

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

2. 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
       }
     }
   }
   

3. 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

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:

# 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