# redis/mcp-redis architecture

> Architecture diagram of the GitHub repository redis/mcp-redis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redis/mcp-redis
- Repository: https://github.com/redis/mcp-redis

## Overview

##### Project Type and Purpose
- This is an **open-source Python MCP Server** that provides a natural-language interface to Redis for AI agents.
- Purpose: let MCP clients (OpenAI Agents SDK, Claude Desktop, VS Code, etc.) issue natural-language commands which are translated into Redis operations on strings, hashes, lists, sets, sorted sets, streams, JSON, vector indexes, pub/sub, and server management.

##### File Structure
- Top-level: Dockerfile/.dockerignore, pyproject.toml, uv.lock, smithery.yaml, README.md, LICENSE
- src/
- common/
- config.py: loads environment variables (REDIS_HOST, MCP_TRANSPORT, etc.)
- connection.py: sets up Redis client (single node or cluster)
- server.py: initializes and runs the MCP protocol server (stdio or SSE)
- tools/
- hash.py, list.py, set.py, sorted_set.py, stream.py, pub_sub.py, json.py, redis_query_engine.py, server_management.py, misc.py
- Each module implements one category of Redis commands and exposes them as MCP “tools.”
- main.py: entry point—discovers tools, registers them, starts the server loop
- version.py

##### README for Additional Insights
- Transport options: **stdio** (default) or **sse** (HTTP SSE endpoint at /sse).
- Deployment: local CLI via `uv run`, Docker image (Dockerfile), or official `mcp/redis` image.
- Integration points: OpenAI Agents SDK, Claude Desktop, VS Code extension.
- Configurable via ENV vars for Redis connection, SSL, cluster mode, and transport.

##### Elements
- **Clear Labels**: name each component (e.g., “Transport (stdio/SSE)”, “Tool: hash”, “Redis Cluster”)
- Blue rectangles for protocol/transport layers
- Green rectangles for tool handlers

##### Detail Level
- Individual tool categories or group by function (data structures, pub/sub, search).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External MCP Clients"
        direction TB
        OpenAI["OpenAI Agents SDK"]:::external
        Claude["Claude Desktop"]:::external
        VSCode["VS Code Extension"]:::external
        CURL["curl (CLI)"]:::external
        ExampleClient["Example Client Script"]:::external
    end

    %% Deployment Options
    subgraph "Deployment"
        direction TB
        CLI["Local CLI (uv run)"]:::infra
        Docker["Docker Container"]:::infra
        DockerfileNode["Dockerfile"]:::infra
        PyProject["pyproject.toml"]:::infra
        SmitheryCI["smithery.yaml"]:::infra
    end

    %% Transport Layer
    subgraph "Transport Layer" 
        direction TB
        Stdio["Transport: stdio"]:::transport
        SSE["Transport: SSE (/sse)"]:::transport
    end

    %% Server Core
    subgraph "MCP Server Core"
        direction TB
        ConfigLoader["Configuration Loader"]:::config
        ConnManager["Redis Connection Manager"]:::config
        ServerBootstrap["Server Bootstrap & Event Loop"]:::config
        EntryPoint["Entry Point & Dispatcher"]:::config
        VersionInfo["Version Info"]:::config
    end

    %% Tool Plugins
    subgraph "Tool Plugins" 
        direction TB
        Strings["Tool: Strings"]:::tool
        Hashes["Tool: Hashes"]:::tool
        Lists["Tool: Lists"]:::tool
        Sets["Tool: Sets"]:::tool
        SortedSets["Tool: Sorted Sets"]:::tool
        Streams["Tool: Streams"]:::tool
        PubSub["Tool: Pub/Sub"]:::tool
        JSONTool["Tool: JSON"]:::tool
        QueryEngine["Tool: Redis Query Engine"]:::tool
        ServerMgmt["Tool: Server Management"]:::tool
        Misc["Tool: Miscellaneous"]:::tool
    end

    %% Data Layer
    Redis["Redis Database\n(single node or cluster)"]:::db

    %% Connections
    OpenAI -->|MCP Request| Stdio
    Claude -->|MCP Request| Stdio
    VSCode -->|MCP Request| Stdio
    CURL -->|MCP Request| Stdio
    ExampleClient -->|MCP Request| Stdio

    Stdio -->|deserialize| ServerBootstrap
    SSE -->|HTTP EventStream| ServerBootstrap

    ServerBootstrap -->|load config| ConfigLoader
    ConfigLoader -->|init| ConnManager
    ConnManager -->|provide client| ServerBootstrap

    ServerBootstrap -->|start| EntryPoint
    EntryPoint -->|discover tools| Strings
    EntryPoint -->|discover tools| Hashes
    EntryPoint -->|discover tools| Lists
    EntryPoint -->|discover tools| Sets
    EntryPoint -->|discover tools| SortedSets
    EntryPoint -->|discover tools| Streams
    EntryPoint -->|discover tools| PubSub
    EntryPoint -->|discover tools| JSONTool
    EntryPoint -->|discover tools| QueryEngine
    EntryPoint -->|discover tools| ServerMgmt
    EntryPoint -->|discover tools| Misc
    EntryPoint -->|serve| VersionInfo

    Strings -->|execute| ConnManager
    Hashes -->|execute| ConnManager
    Lists -->|execute| ConnManager
    Sets -->|execute| ConnManager
    SortedSets -->|execute| ConnManager
    Streams -->|execute| ConnManager
    PubSub -->|execute| ConnManager
    JSONTool -->|execute| ConnManager
    QueryEngine -->|execute| ConnManager
    ServerMgmt -->|execute| ConnManager
    Misc -->|execute| ConnManager

    ConnManager -->|run command| Redis
    Redis -->|response| ConnManager

    ConnManager -->|result| ServerBootstrap
    ServerBootstrap -->|serialize response| Stdio
    ServerBootstrap -->|serialize response| SSE
    Stdio -->|MCP Response| OpenAI
    Stdio -->|MCP Response| Claude
    Stdio -->|MCP Response| VSCode
    Stdio -->|MCP Response| CURL
    Stdio -->|MCP Response| ExampleClient
    SSE -->|MCP Response| OpenAI
    SSE -->|MCP Response| Claude
    SSE -->|MCP Response| VSCode
    SSE -->|MCP Response| CURL
    SSE -->|MCP Response| ExampleClient

    CLI --> DockerfileNode
    DockerfileNode --> Docker
    PyProject --> CLI
    SmitheryCI --> Docker

    %% Click Events
    click ConfigLoader "https://github.com/redis/mcp-redis/blob/main/src/common/config.py"
    click ConnManager "https://github.com/redis/mcp-redis/blob/main/src/common/connection.py"
    click ServerBootstrap "https://github.com/redis/mcp-redis/blob/main/src/common/server.py"
    click EntryPoint "https://github.com/redis/mcp-redis/blob/main/src/main.py"
    click Strings "https://github.com/redis/mcp-redis/blob/main/src/tools/string.py"
    click Hashes "https://github.com/redis/mcp-redis/blob/main/src/tools/hash.py"
    click Lists "https://github.com/redis/mcp-redis/blob/main/src/tools/list.py"
    click Sets "https://github.com/redis/mcp-redis/blob/main/src/tools/set.py"
    click SortedSets "https://github.com/redis/mcp-redis/blob/main/src/tools/sorted_set.py"
    click Streams "https://github.com/redis/mcp-redis/blob/main/src/tools/stream.py"
    click PubSub "https://github.com/redis/mcp-redis/blob/main/src/tools/pub_sub.py"
    click JSONTool "https://github.com/redis/mcp-redis/blob/main/src/tools/json.py"
    click QueryEngine "https://github.com/redis/mcp-redis/blob/main/src/tools/redis_query_engine.py"
    click ServerMgmt "https://github.com/redis/mcp-redis/blob/main/src/tools/server_management.py"
    click Misc "https://github.com/redis/mcp-redis/blob/main/src/tools/misc.py"
    click VersionInfo "https://github.com/redis/mcp-redis/blob/main/src/version.py"
    click DockerfileNode "https://github.com/redis/mcp-redis/tree/main/Dockerfile"
    click PyProject "https://github.com/redis/mcp-redis/blob/main/pyproject.toml"
    click SmitheryCI "https://github.com/redis/mcp-redis/blob/main/smithery.yaml"
    click ExampleClient "https://github.com/redis/mcp-redis/blob/main/examples/redis_assistant.py"

    %% Styles
    classDef external fill:#d0e1f9,stroke:#4a90e2,color:#333,shape:cloud
    classDef transport fill:#b3cde0,stroke:#6497b1,color:#000
    classDef config fill:#ece2f0,stroke:#a5c8e0,color:#000
    classDef tool fill:#c7e9c0,stroke:#74c476,color:#000
    classDef db fill:#fdae61,stroke:#e6550d,color:#000,shape:cylinder
    classDef infra fill:#f0f0f0,stroke:#999,color:#333 shape:box
```
