# cache-mcp

MCP server that exposes a key-value cache (Valkey / Redis compatible) as tools over the Model Context Protocol.

## Features

- Three MCP tools: `cache_get`, `cache_set`, `cache_delete`
- Per-user key namespacing via `user_id`
- Optional global prefix (`CACHE_PREFIX`) to avoid collisions when sharing a Redis instance
- TTL support on `cache_set`
- Two transports: **SSE** (`/sse` + `/messages`) and **direct HTTP** (`/mcp`, `/`)
- Health check at `/health`
- Stateless — bring your own Redis

## Installation

### Docker (recommended)

docker pull ghcr.io/dolphin2702/cache-mcp:latest

### From source (uv / uvx)

uvx --from "git+https://github.com/dolphin2702/cache-mcp.git@v0.1.0" cache-mcp

### From source (pip)

pip install "git+https://github.com/dolphin2702/cache-mcp.git@v0.1.0"
cache-mcp

## Configuration

| Variable | Default | Description |
|---|---|---|
| `CACHE_HOST` | `127.0.0.1` | Cache backend host |
| `CACHE_PORT` | `6379` | Cache backend port |
| `CACHE_DB` | `0` | Redis DB index |
| `CACHE_PREFIX` | `""` | Prefix added to every key. Useful when sharing a Redis instance with other apps (e.g. Mailu). |
| `HOST` | `0.0.0.0` | Bind address |
| `PORT` | `3002` | HTTP port |

## Deployment examples


Scenario	File
Connect to an existing Redis	examples/docker-compose.external-redis.yml
Bundled Redis (quick try-out)	examples/docker-compose.bundled-redis.yml
Share Redis with Mailu	examples/docker-compose.mailu-redis.yml
Sharing Redis with another app? Set CACHE_PREFIX=cachemcp: or use a
separate CACHE_DB to avoid key collisions.

## MCP Client Configuration

SSE transport

{
  "mcpServers": {
    "cache-mcp": {
      "url": "http://localhost:3002/sse"
    }
  }
}

## stdio via uvx

{
  "mcpServers": {
    "cache-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dolphin2702/cache-mcp.git@v0.1.0", "cache-mcp"],
      "env": {
        "CACHE_HOST": "192.168.203.2",
        "CACHE_PORT": "6379",
        "CACHE_PREFIX": "cachemcp:"
      }
    }
  }
}

## Tools

**cache_get**

Get a value from cache.

Arguments:
- key (string, required)
- user_id (string, default "default")
Returns: value or "null".

**cache_set**

Store a value with TTL.

Arguments:
- key (string, required)
- value (string, required)
- ttl (integer, default 3600 seconds)
- user_id (string, default "default")
Returns: "ok".

**cache_delete**

Delete a key.

Arguments:
- key (string, required)
- user_id (string, default "default")
Returns: "ok".

## HTTP API

| Переменная | По умолчанию | Описание |
|---|---|---|
| `CACHE_HOST` | `127.0.0.1` | Хост кэш-бэкенда |
| `CACHE_PORT` | `6379` | Порт кэш-бэкенда |
| `CACHE_DB` | `0` | Номер БД в Redis |
| `CACHE_PREFIX` | `""` | Префикс, добавляемый к каждому ключу. Полезен при использовании общего Redis с другими приложениями (например, Mailu). |
| `HOST` | `0.0.0.0` | Адрес прослушивания |
| `PORT` | `3002` | HTTP-порт |

## Key format

Final Redis key:

{CACHE_PREFIX}{user_id}:{key}

Example with CACHE_PREFIX=cachemcp:, user_id=alice, key=session:

cachemcp:alice:session

## Development

git clone git@github.com:dolphin2702/cache-mcp.git
cd cache-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cache-mcp

## License

MIT