---
title: storage
sidebarTitle: storage
---

# `fastmcp.utilities.storage`


Key-value storage utilities for persistent data management.

## Classes

### `KVStorage` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L16" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Protocol for key-value storage of JSON data.


**Methods:**

#### `get` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L19" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, key: str) -> dict[str, Any] | None
```

Get a JSON dict by key.


#### `set` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, key: str, value: dict[str, Any]) -> None
```

Store a JSON dict by key.


#### `delete` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(self, key: str) -> None
```

Delete a value by key.


### `JSONFileStorage` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


File-based key-value storage for JSON data with automatic metadata tracking.

Each key-value pair is stored as a separate JSON file on disk.
Keys are sanitized to be filesystem-safe.

The storage automatically wraps all data with metadata:
- timestamp: Timestamp when the entry was last written

**Args:**
- `cache_dir`: Directory for storing JSON files


**Methods:**

#### `get` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, key: str) -> dict[str, Any] | None
```

Get a JSON dict from storage by key.

**Args:**
- `key`: The key to retrieve

**Returns:**
- The stored dict or None if not found


#### `set` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, key: str, value: dict[str, Any]) -> None
```

Store a JSON dict with metadata.

**Args:**
- `key`: The key to store under
- `value`: The dict to store


#### `delete` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(self, key: str) -> None
```

Delete a value from storage.

**Args:**
- `key`: The key to delete


#### `cleanup_old_entries` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
cleanup_old_entries(self, max_age_seconds: int = 30 * 24 * 60 * 60) -> int
```

Remove entries older than the specified age.

Uses the timestamp field to determine age.

**Args:**
- `max_age_seconds`: Maximum age in seconds (default 30 days)

**Returns:**
- Number of entries removed


### `InMemoryStorage` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


In-memory key-value storage for JSON data.

Simple dict-based storage that doesn't persist across restarts.
Useful for testing or environments where file storage isn't available.


**Methods:**

#### `get` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L194" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get(self, key: str) -> dict[str, Any] | None
```

Get a JSON dict from memory by key.


#### `set` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L198" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
set(self, key: str, value: dict[str, Any]) -> None
```

Store a JSON dict in memory.


#### `delete` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/storage.py#L202" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(self, key: str) -> None
```

Delete a value from memory.

