MCP Memory Server
A lightweight Model Context Protocol (MCP) server that exposes a simple key‑value store to other agents or CLI tools.
The server is built with fastmcp and uses a JSON file as persistent storage.
Table of Contents
- Features
- Prerequisites
- Installation
- Running the Server
- Running the Client
- Example Usage
- Project Structure
Features
| Operation | Description |
|---|---|
set |
Store a value under a key (optionally in a namespace). |
get |
Retrieve a stored value. |
delete |
Remove a key from storage. |
keys |
List all keys, optionally filtered by pattern or namespace. |
All operations are performed through the MCP protocol over STDIO.
Prerequisites
- Python 3.10+
- pip
Installation
# Clone the repository (or copy the files)
git clone https://github.com/your-org/mcp-memory-server.git
cd mcp-memory-server
# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies
pip install fastmcp pydantic python-dotenv
Tip: The
memory_server.pyandmemory_client.pyfiles are self‑contained; no additional packages are required beyond those listed.
Running the Server
python memory_server.py
The server starts listening on STDIO.
It will create (or load) a file named memory_data.json in the current directory to persist data.
Server output example
[Memory-Server] Listening on stdin/stdout...
Running the Client
python memory_client.py
The client demonstrates basic usage: setting, getting, listing keys, and deleting a key.
It communicates with the server over STDIO using fastmcp.
Client output example
Set key 'foo' to value 'bar'
Get key 'foo': bar
All keys: ['foo']
Deleted key 'foo'
All keys after deletion: []
Example Usage
Below is a quick script that shows how you can interact with the server programmatically.
from fastmcp import FastMCPClient
import json
# Connect to the running MCP server (STDIO)
client = FastMCPClient("Memory-Server")
# Set a key
client.send({"action": "set", "key": "greeting", "value": "Hello, world!"})
# Get the key
response = client.receive()
print(response) # {'status': 'ok', 'value': 'Hello, world!'}
# List all keys
client.send({"action": "keys"})
print(client.receive()) # {'status': 'ok', 'keys': ['greeting']}
# Delete the key
client.send({"action": "delete", "key": "greeting"})
print(client.receive()) # {'status': 'ok'}
Note: The client and server communicate via JSON messages.
Each message must contain an"action"field that matches one of the supported operations.
Project Structure
mcp-memory-server/
├── memory_server.py # MCP server implementation
├── memory_client.py # Demo client script
└── README.md # This file
memory_server.py– defines theMemoryServerclass and starts the MCP service.memory_client.py– simple CLI client that exercises all operations.
Feel free to extend the server with authentication, more sophisticated storage backends, or additional MCP actions. Happy hacking!