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

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 (the IAM-enabled user with IAM auth)	`None`
`VALKEY_PWD`	Password for authentication (note: not `VALKEY_PASSWORD`); ignored with IAM auth	`""`
`VALKEY_USE_SSL`	Enable TLS (forced on with IAM auth)	`false`
`VALKEY_SSL_CA_CERTS`	Path to CA certificate (PEM) for TLS verification	`None`
`VALKEY_CLUSTER_MODE`	Enable cluster mode	`false`
`VALKEY_IAM_AUTH`	Use Amazon ElastiCache IAM authentication instead of a password	`false`
`VALKEY_CACHE_NAME`	ElastiCache cache name for IAM auth (not the endpoint hostname)	`None`
`VALKEY_REGION`	Region of the cache for IAM auth	`None`
`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`
`VALKEY_GLIDE_LOG_LEVEL`	GLIDE core log level (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `OFF`)	`WARN`

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.

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.
`WRONGPASS` or authentication failure with `VALKEY_IAM_AUTH`	Wrong `VALKEY_USERNAME`, wrong `VALKEY_CACHE_NAME`, missing `elasticache:Connect` permission, or expired temporary credentials	Check the username is in the cache's user group, `VALKEY_CACHE_NAME` is the cache name (not the hostname), the IAM principal has `elasticache:Connect` on both the cache ARN and the user ARN, and your AWS credentials are still valid.
TLS handshake failure to a public endpoint	Something on the network path is downgrading or intercepting TLS; public endpoints accept TLS 1.3 only	GLIDE negotiates TLS 1.3 natively. Check for a proxy or TLS-inspecting device between the MCP server and the endpoint.
`ERR service is not available` on a new connection	Generic error for any failure before authentication completes: IAM auth temporarily unavailable, IAM auth rate limiting, or engine overload (`BUSY`, `CLUSTERDOWN`, max clients)	Reduce the rate of new connections and retry with exponential backoff. If the rate is normal and the error persists, check the cache's metrics and the AWS Health Dashboard.
`ERR IAM Authentication service is not available` or `ERR Exceeded limit of IAM Authentication requests` on an established connection	IAM auth temporarily unavailable, or IAM auth rate limit hit during re-authentication	Reduce the rate of re-authentications and retry with exponential backoff.
Connection timeout to an ElastiCache public endpoint	Wrong endpoint address, or outbound TCP 6379 blocked	Verify `Endpoint.Address` from the console or CLI and that your network allows outbound TCP 6379.

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​