Amazon ElastiCache/MemoryDB Valkey MCP Server

An AWS Labs Model Context Protocol (MCP) server for Amazon ElastiCache Valkey datastores.

Features

This MCP server provides tools to operate on Valkey data types. For example, it allows an agent to operate with Valkey Strings using commands such as SET, SETRANGE, GET, GETRANGE, APPEND, INCREMENT and more.

Supported Data Types

Strings- Store, retrieve, append, increment, decrement, length and more.
Lists- Manage List collections with push/pop operations.
Sets and Sorted Sets- Store and retrieve items from Sets.
Hashes- Store and retrieve items in Hashes. Check for existence of items in a hash, increment item values in a Hash, and more.
Streams- Store, retrieve, trim items in Streams.
Bitmaps- Bitmaps let you perform bitwise operations on strings.
JSONs- Store and retrieve JSON documents with path-based access.
HyperLogLog- Store and count items in HyperLogs.

Advanced Features

Cluster Support: Support for standalone and clustered Valkey deployments.
SSL/TLS Security: Configure secure connections using SSL/TLS.
Connection Pooling: Pools connections by default to enable efficient connection management.

Prerequisites

Install uv from Astral or the GitHub README
Install Python using uv python install 3.10
Access to a Valkey datastore.
For instructions to connect to an Amazon ElastiCache/MemoryDB Valkey datastore click here.

Installation

Here are some ways you can work with MCP across AWS tools (e.g., for Amazon Q Developer CLI MCP, ~/.aws/amazonq/mcp.json):

{
  "mcpServers": {
    "awslabs.valkey-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.valkey-mcp-server@latest"
      ],
      "env": {
        "VALKEY_HOST": "127.0.0.1",
        "VALKEY_PORT": "6379",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}

Or using Docker after a successful docker build -t awslabs/valkey-mcp-server .:

{
  "mcpServers": {
    "awslabs.valkey-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "FASTMCP_LOG_LEVEL=ERROR",
        "--env",
        "VALKEY_HOST=127.0.0.1",
        "--env",
        "VALKEY_PORT=6379",
        "awslabs/valkey-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuration

The server can be configured using the following environment variables:

Name	Description	Default Value
`VALKEY_HOST`	ElastiCache Primary Endpoint or MemoryDB Cluster Endpoint or Valkey IP or hostname	`"127.0.0.1"`
`VALKEY_PORT`	Valkey port	`6379`
`VALKEY_USERNAME`	Default database username	`None`
`VALKEY_PWD`	Default database password	`""`
`VALKEY_USE_SSL`	Enables or disables SSL/TLS	`False`
`VALKEY_CA_PATH`	CA certificate for verifying server	`None`
`VALKEY_SSL_KEYFILE`	Client's private key file	`None`
`VALKEY_SSL_CERTFILE`	Client's certificate file	`None`
`VALKEY_CERT_REQS`	Server certificate verification	`"required"`
`VALKEY_CA_CERTS`	Path to trusted CA certificates	`None`
`VALKEY_CLUSTER_MODE`	Enable Valkey Cluster mode	`False`

Example Usage

Here are some example natural language queries that the server can handle:

"Store user profile data in a hash"
"Add this event to the activity stream"
"Cache API response for 5 minutes"
"Store JSON document with nested fields"
"Add score 100 to user123 in leaderboard"
"Get all members of the admins set"

Development

Running Tests

uv venv
source .venv/bin/activate
uv sync
uv run --frozen pytest

Building Docker Image

docker build -t awslabs/valkey-mcp-server .

Running Docker Container

docker run -p 8080:8080 \
  -e VALKEY_HOST=host.docker.internal \
  -e VALKEY_PORT=6379 \
  awslabs/valkey-mcp-server

Amazon ElastiCache/MemoryDB Valkey MCP Server