MCP‑Memory Server

A lightweight Model Context Protocol (MCP) server that exposes a simple key/value memory store for agents and other clients.
The project contains two scripts:

File	Purpose
`memory_server.py`	Runs the MCP server, exposing set, get and delete operations on a JSON‑backed storage.
`memory_client.py`	Demonstrates how to connect to the server and use its tools from a client script.

Why MCP?
MCP is a lightweight protocol for exchanging structured data between agents, services or CLI utilities. By running this server as a separate process we enable distributed multi‑agent systems to share state without tight coupling.

📦 Installation

# Create and activate a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate

# Install the required packages
pip install fastmcp pydantic python-dotenv

Tip:
fastmcp is a minimal framework for building MCP servers and clients.
pydantic is used internally by fastmcp for data validation.

🚀 Running the Server

python memory_server.py

The server starts on the default port 8000 (you can change it in the script).
It will create a file called memory_data.json in the current directory to persist data between restarts.

Available Tools

Tool	Parameters	Description
`set`	`key: str`, `value: Any`	Stores a value under the given key.
`get`	`key: str`	Retrieves the value for the key (or `null`).
`delete`	`key: str`	Removes the key from storage.

🧪 Running the Client

python memory_client.py

The client script demonstrates:

Setting a value (foo = "bar").
Getting that value back.
Deleting the key and verifying it’s gone.

You can also use the client interactively by editing memory_client.py or by sending raw MCP messages via another tool (e.g., curl, Postman, or a custom agent).

📄 Example Usage

# memory_client.py snippet

from fastmcp import FastMCPClient

client = FastMCPClient("Memory-Server", host="localhost", port=8000)

# Set a key/value pair
client.call_tool("set", {"key": "greeting", "value": "Hello, world!"})

# Retrieve the value
response = client.call_tool("get", {"key": "greeting"})
print(response)  # Output: Hello, world!

# Delete the key
client.call_tool("delete", {"key": "greeting"})

# Verify deletion
assert client.call_tool("get", {"key": "greeting"}) is None

Feel free to integrate this server into your own agent framework or use it as a standalone memory service.

📁 Project Structure

.
├── memory_server.py   # MCP server implementation
├── memory_client.py   # Example client script
└── memory_data.json   # (generated) persistent storage

🔧 Customization

Port – change the port argument in FastMCP("Memory-Server", port=8000) inside memory_server.py.
Storage Path – modify self.storage_path = Path("./memory_data.json") to point elsewhere.
Additional Tools – add new methods decorated with @self.mcp.tool(...) following the pattern in the script.

📜 License

This project is released under the MIT license. Feel free to fork, extend or use it in your own projects.

3.3 KiB Raw Blame History Unescape Escape