MCP Memory Server

A lightweight Model Context Protocol (MCP) server that exposes a simple JSON‑based memory store over HTTP.
It is built on top of the fastmcp framework and uses pydantic for data validation and python-dotenv to load configuration.

Why this project?
In multi‑agent systems agents often need a shared, persistent context. The MCP server provides a single source of truth that can be queried by any agent via the standardized protocol.

📦 Features

Feature	Description
Namespaces	Organise data into logical groups (`/namespace/key`).
CRUD	Create, read, update and delete keys.
Search	Find keys that match a pattern or contain a substring.
Persistence	All data is stored in a single JSON file on disk.
Fast & Async	Built with `fastmcp` – fast, type‑safe, async HTTP server.

📋 Prerequisites

Python 3.10+
pip (or any other package manager)

The project uses only pure‑Python dependencies; no external services are required.

⚙️ Installation

# Clone the repository
git clone https://github.com/your-org/mcp-memory-server.git
cd mcp-memory-server

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

# Install dependencies
pip install -r requirements.txt

requirements.txt contains:

fastmcp>=0.1.0
pydantic>=2.0
python-dotenv>=1.0
uvicorn>=0.30.0   # optional, for running with ASGI server

🚀 Running the Server

The server reads configuration from a .env file (or environment variables).
Create a .env in the project root:

# .env
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
DATA_FILE=data/memory.json   # relative to project root

Start the server with:

python memory_server.py

The server will listen on http://127.0.0.1:8000 and expose the following endpoints:

Method	Path	Action
POST	`/namespace/key`	Create/Update a key
GET	`/namespace/key`	Retrieve a key
DELETE	`/namespace/key`	Delete a key
GET	`/search?query=...`	Search keys

📚 Example Usage

Below is a minimal example of how an agent (or any HTTP client) can interact with the server.

import httpx
from pathlib import Path

BASE_URL = "http://127.0.0.1:8000"

# 1️⃣ Create a key
payload = {"value": "Hello, MCP!"}
resp = httpx.post(f"{BASE_URL}/memory/greeting", json=payload)
print(resp.status_code)   # 201 Created

# 2️⃣ Read the key
resp = httpx.get(f"{BASE_URL}/memory/greeting")
print(resp.json())        # {"value":"Hello, MCP!"}

# 3️⃣ Search for keys containing "greet"
resp = httpx.get(f"{BASE_URL}/search?query=greet")
print(resp.json())        # ["memory/greeting"]

# 4️⃣ Delete the key
resp = httpx.delete(f"{BASE_URL}/memory/greeting")
print(resp.status_code)   # 204 No Content

Tip: The memory_client.py module contains a thin wrapper around these HTTP calls, making it easier to integrate into your agents.

📁 Project Structure

mcp-memory-server/
├── memory_server.py   # FastMCP server implementation
├── memory_client.py   # Helper client for interacting with the server
├── .env              # Environment configuration (example)
├── requirements.txt  # Dependencies
└── README.md         # This file

🧪 Testing

# Run unit tests (if any)
pytest tests/

Currently there are no automated tests, but you can easily add them using pytest and httpx.

🤝 Contributing

Feel free to open issues or pull requests.
Please follow the standard GitHub workflow:

Fork the repo
Create a feature branch (feature/your-feature)
Commit & push
Open a Pull Request

3.9 KiB Raw Blame History Unescape Escape