Amazon ElastiCache/MemoryDB for Valkey MCP Server

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

Tool	What It Does
`manage_index`	Create, drop, inspect, or list search indices. Accepts structured schema definitions with TEXT, NUMERIC, TAG, and VECTOR fields. Defaults to COSINE distance + HNSW algorithm.
`add_documents`	Ingest documents with optional embedding generation. Supports Bedrock, OpenAI, and Ollama providers. Auto-creates the index if missing.
`search`	Unified semantic, text, hybrid, and find-similar search. Auto-detects mode from parameters, or accepts an explicit `mode` override.
`aggregate`	Structured pipeline builder for FT.AGGREGATE. Supports GROUPBY, SORTBY, APPLY, FILTER, and LIMIT stages with 12 REDUCE functions.

Valkey JSON Intelligence — 5 tools

Tool	What It Does
`json_get`	Get a JSON value at a path from a Valkey key.
`json_set`	Set a JSON value at a path with optional TTL.
`json_arrappend`	Append values to a JSON array at a path.
`json_arrpop`	Pop an element from a JSON array at a path.
`json_arrtrim`	Trim a JSON array to a specified range.

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

Tool	Tier	What It Does
`valkey_read`	Safe	Read-only commands (GET, HGETALL, SCAN, INFO, etc.). Always available, even in readonly mode.
`valkey_write`	Write	Mutating commands (SET, HSET, DEL, LPUSH, etc.). Destructive commands blocked. Disabled in readonly mode.
`valkey_admin`	Admin	Destructive commands (FLUSHALL, CONFIG SET, EVAL, etc.). Disabled by default — requires `VALKEY_ADMIN_ENABLED=true` + `confirm=True`.

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

Install uv from Astral
Install Python using uv python install 3.10
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
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)
For Amazon ElastiCache/MemoryDB connection instructions, see ELASTICACHECONNECT.md.

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

Variable	Description	Default
`MCP_TRANSPORT`	Transport protocol (`stdio`, `sse`)	`stdio`

Valkey Connection

Variable	Description	Default
`VALKEY_HOST`	Valkey hostname or IP	`127.0.0.1`
`VALKEY_PORT`	Valkey port	`6379`
`VALKEY_USERNAME`	Username for authentication	`None`
`VALKEY_PWD`	Password for authentication (note: not `VALKEY_PASSWORD`)	`""`
`VALKEY_USE_SSL`	Enable TLS	`false`
`VALKEY_SSL_CA_CERTS`	Path to CA certificate (PEM) for TLS verification	`None`
`VALKEY_CLUSTER_MODE`	Enable cluster mode	`false`
`VALKEY_VECTOR_ALGORITHM`	Default vector index algorithm (`HNSW` or `FLAT`)	`HNSW`
`VALKEY_VECTOR_DISTANCE_METRIC`	Default vector distance metric (`COSINE`, `L2`, or `IP`)	`COSINE`
`VALKEY_ADMIN_ENABLED`	Enable admin tier (destructive commands)	`false`

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.

Variable	Description	Default
`EMBEDDING_PROVIDER`	Provider: `bedrock`, `openai`, `ollama`, or `hash`	`bedrock`

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.

Variable	Description	Default
`AWS_REGION`	AWS region	`us-east-1`
`BEDROCK_MODEL_ID`	Model ID	`amazon.nova-2-multimodal-embeddings-v1:0`
`BEDROCK_NORMALIZE`	Normalize embeddings	`None`
`BEDROCK_DIMENSIONS`	Embedding dimensions	`None` (model default)
`BEDROCK_INPUT_TYPE`	Input type	`None`
`BEDROCK_MAX_ATTEMPTS`	Max retry attempts	`3`
`BEDROCK_MAX_POOL_CONNECTIONS`	Connection pool size	`50`
`BEDROCK_RETRY_MODE`	Retry mode	`adaptive`

OpenAI

Variable	Description	Default
`OPENAI_API_KEY`	API key (required)	`None`
`OPENAI_MODEL`	Model name	`text-embedding-3-small`

Ollama

Variable	Description	Default
`OLLAMA_HOST`	Ollama endpoint URL (protocol required, e.g., `http://localhost:11434`)	`http://localhost:11434`
`OLLAMA_EMBEDDING_MODEL`	Model name	`nomic-embed-text`

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

Problem	Cause	Fix
`Connection refused` or `timed out`	Valkey not running or wrong host/port	Verify `VALKEY_HOST` and `VALKEY_PORT`. Test with `valkey-cli -h <host> -p <port> PING`.
`NoCredentialsError` on semantic search	Bedrock is the default provider but no AWS credentials configured	Set `EMBEDDING_PROVIDER=ollama` or configure AWS credentials.
`Unknown command 'FT.CREATE'`	Valkey Search module not loaded	Use `valkey/valkey-bundle` Docker image or load the search module.
`Unknown command 'JSON.GET'`	Valkey JSON module not loaded	Use `valkey/valkey-bundle` Docker image or load the JSON module.
Docker: `Connection refused` to `127.0.0.1`	Container loopback is not the host	Use `VALKEY_HOST=host.docker.internal` (macOS/Windows) or `--network host` (Linux).
`Request URL is missing 'http://'`	`OLLAMA_HOST` set without protocol	Include the protocol: `http://localhost:11434`, not just `localhost:11434`.
No output from server	`FASTMCP_LOG_LEVEL=ERROR` suppresses info	Set `FASTMCP_LOG_LEVEL=INFO` or `DEBUG` for 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

Features​

Valkey AI Search — 4 tools​

Valkey JSON Intelligence — 5 tools​

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

Additional Features​

Prerequisites​

Quickstart​

Installation​

MCP Configuration​

Windows Installation​

Docker​

Configuration​

Server​

Valkey Connection​

Embeddings Provider​

Bedrock​

OpenAI​

Ollama​

Example Usage​

Troubleshooting​

Tool Name Collisions​

Development​

Running Tests​

Building Docker Image​

Running Docker Container​