Amazon ElastiCache/MemoryDB Valkey MCP Server

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

Features

This MCP server provides 12 purpose-built tools for AI agents working with Valkey. The tool surface is designed to minimize token costs and agent error rates by accepting structured JSON input and handling command translation internally.

Valkey AI Search — 4 tools

Valkey JSON Intelligence — 5 tools

Valkey Command Runner — 3 tools (3-tier safety)

3-tier safety model: valkey_read (always safe) → valkey_write (mutations, no destructive) → valkey_admin (opt-in only, disabled by default). An agent cannot accidentally FLUSHALL a staging cluster.

Additional Features

• Valkey-GLIDE: Built on Valkey GLIDE for async-native performance.
• Cluster Support: Standalone and clustered Valkey deployments.
• SSL/TLS Security: Secure connections via TLS with CA certificate verification.
• Readonly Mode: Prevent write operations with --readonly.
• Multi-provider Embeddings: Bedrock, OpenAI, Ollama, with automatic fallback.
• Health Check: GET /health endpoint for ALB target group health checks.

Prerequisites

1. Install uv from Astral
2. Install Python using uv python install 3.10
3. Access to a Valkey datastore:
   • AI Search tools require the Valkey Search module
   • JSON tools require the Valkey JSON module
   • The valkey/valkey-bundle Docker image includes both modules
4. Embedding provider credentials (only needed for semantic search with add_documents and search):
   • Bedrock (default): Requires AWS credentials — AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, AWS_PROFILE, or an IAM role. Without credentials, semantic search will fail with a NoCredentialsError.
   • OpenAI: Requires OPENAI_API_KEY
   • Ollama: Requires a running Ollama instance (no credentials needed)
5. For Amazon ElastiCache/MemoryDB connection instructions, see ELASTICACHECONNECT.md. ElastiCache Serverless caches with a public endpoint need no EC2 jump host or tunnel: set VALKEY_IAM_AUTH=true and connect directly over the internet with IAM authentication.

Quickstart

Start a local Valkey instance with Search and JSON modules:

docker run -d --name valkey -p 6379:6379 valkey/valkey-bundle:latest

Verify it's running:

docker exec valkey valkey-cli PING
# Should return: PONG

Run the MCP server (using Ollama for embeddings — no AWS credentials needed):

uvx awslabs.valkey-mcp-server@latest

Or with Ollama embeddings for semantic search:

EMBEDDING_PROVIDER=ollama uvx awslabs.valkey-mcp-server@latest

Try these example queries in your AI IDE:

"Create a search index called products with title (TEXT), category (TAG), and price (NUMERIC) fields"
"Add 3 product documents to the products index"
"Search for electronics in the products index"
"Show me the average price by category"

Installation

Kiro	Cursor	VS Code

MCP Configuration

Add the following to your MCP settings file (e.g., ~/.kiro/settings/mcp.json for Kiro, .cursor/mcp.json for Cursor, or .vscode/mcp.json for VS Code):

{
  "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"
      }
    }
  }
}

Tip: Use FASTMCP_LOG_LEVEL=INFO or DEBUG during initial setup to see connection and tool registration output. Switch to ERROR for production use.

The default embedding provider is Bedrock, which requires AWS credentials. To use Ollama instead (no credentials needed), add:

        "EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434"

Readonly mode (disables all write operations — embedding config is only needed if you use semantic search):

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

Windows Installation

{
  "mcpServers": {
    "awslabs.valkey-mcp-server": {
      "command": "uv",
      "args": [
        "tool", "run", "--from",
        "awslabs.valkey-mcp-server@latest",
        "awslabs.valkey-mcp-server.exe"
      ],
      "env": {
        "VALKEY_HOST": "127.0.0.1",
        "VALKEY_PORT": "6379",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Docker

Build the image first:

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

MCP configuration (use host.docker.internal to reach Valkey on the host; on Linux, use --network host instead):

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

Readonly mode with Docker:

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

Running the Docker container directly:

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

Configuration

Server

Valkey Connection

IAM authentication (required for ElastiCache Serverless caches with a public endpoint): set VALKEY_IAM_AUTH=true, VALKEY_USERNAME (e.g. default.iam-user), VALKEY_CACHE_NAME, and VALKEY_REGION (falls back to AWS_REGION, AWS_DEFAULT_REGION, then the AWS config chain). GLIDE generates the IAM auth token from the default AWS credential chain and refreshes it automatically; TLS is enabled automatically and VALKEY_PWD is ignored. See ELASTICACHECONNECT.md.

Embeddings Provider

Embedding generation is used by add_documents (to generate vectors) and search (for semantic/hybrid modes). If you only use text search, JSON tools, or manage_index, no embedding provider is needed.

Note: The default provider is Bedrock, which requires AWS credentials. If you don't have AWS credentials configured, set EMBEDDING_PROVIDER=ollama and run a local Ollama instance, or set EMBEDDING_PROVIDER=hash for testing (deterministic, low-quality embeddings).

Bedrock

Credentials via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, AWS_PROFILE, or IAM role.

OpenAI

Ollama

Example Usage

"Create a search index for product data with title, category, price, and embedding fields"
"Add these product documents and generate embeddings from the title field"
"Search for products similar to 'wireless headphones'"
"Find products similar to product:123"
"Show me the average price by category"
"Store this JSON config and set a 1-hour TTL"
"Get the nested value at $.settings.theme from the config key"

Troubleshooting

Tool Name Collisions

This server exposes a tool named search. Other MCP servers (e.g., Atlassian Rovo) may also expose a tool with the same name. When multiple MCP servers are active simultaneously, the AI agent may not be able to distinguish between them, leading to the wrong tool being called.

If you experience this, either:

• Disable the conflicting MCP server when using Valkey search
• Use explicit tool routing if your MCP client supports it (e.g., server-scoped tool names)
• Instruct the agent to use the Valkey search tool specifically by referencing the index name or Valkey-specific parameters

Development

Running Tests

uv venv && source .venv/bin/activate && uv sync

# Unit tests
uv run --frozen pytest tests/ -m "not live and not integration"

# Live integration tests (requires VALKEY_HOST and EMBEDDING_PROVIDER)
uv run --frozen pytest tests/test_search_live.py -m live -v

# Type checking
uv run --frozen pyright

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

Readonly mode:

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