MCP‑Memory Server

A lightweight Model Context Protocol (MCP) server that exposes a simple key/value memory store to any agent or client via the fastmcp protocol.

The project contains two scripts:

File	Purpose
`memory_server.py`	The MCP server – runs as an independent process and listens for requests.
`memory_client.py`	A demo client that connects to the server, stores data and retrieves it.

Why MCP?
In a multi‑agent system agents often need to share state (e.g., user profiles, conversation history). Running a dedicated memory service decouples this shared state from individual agent processes, enabling easier scaling, persistence, and cross‑agent coordination.

Features

Namespace support – store data under arbitrary namespaces (default, session_1234, …).
Simple CRUD API – save_with_namespace, load_from_namespace, delete_from_namespace.
FastMCP integration – uses the fastmcp library for lightweight, async communication.
Zero‑configuration – no external database required; data is kept in memory (restart loses state).

Prerequisites

Component	Minimum version
Python	3.10+
pip	latest

No external services are needed – the server keeps all data in RAM.

Installation

# Clone the repo
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 -r requirements.txt

requirements.txt contains:

fastmcp>=0.2.0
pydantic>=1.10.0
python-dotenv>=1.0.0

Running the Server

The server is a simple Python script that can be started directly or via subprocess.
It listens on an internal IPC channel (via fastmcp), so no network port is exposed.

# Direct execution
python memory_server.py

You should see:

[INFO] MCP Server listening...

Running the Demo Client

The client demonstrates how to connect to the server, store a value, and retrieve it.

python memory_client.py

Output example:

Сохранено: {'status': 'ok'}
Загружено: {'value': 'Алексей', 'namespace': 'default'}

API Reference

The server exposes three tools via MCP:

Tool	Parameters	Returns
`save_with_namespace`	`{key, value, namespace}`	`{'status': 'ok'}`
`load_from_namespace`	`{key, namespace}`	`{'value': <value>, 'namespace': <ns>}`
`delete_from_namespace`	`{key, namespace}`	`{'status': 'deleted'}`

All calls are asynchronous and return JSON‑serializable dictionaries.

Example Usage in an Agent

from fastmcp import Client
import asyncio

async def agent_logic():
    client = Client("python memory_server.py")
    await client.connect()

    # Store a user ID
    await client.call_tool(
        "save_with_namespace",
        {"key": "user_id", "value": 42, "namespace": "session_123"}
    )

    # Later retrieve it
    res = await client.call_tool(
        "load_from_namespace",
        {"key": "user_id", "namespace": "session_123"}
    )
    print(res["value"])   # -> 42

asyncio.run(agent_logic())

Extending the Server

Persistence – wrap the in‑memory store with a simple file or Redis backend.
Authentication – add token checks to Client before processing requests.
Metrics – expose Prometheus metrics for request counts and latency.

Feel free to fork, improve, and contribute!

3.6 KiB Raw Permalink Blame History Unescape Escape