lmdb-mcp

LMDB-MCP

A lightweight, high-performance Model Context Protocol (MCP) server that provides persistent key-value storage using LMDB (Lightning Memory-Mapped Database).

Features

• High Performance: Built on LMDB for lightning-fast read/write operations
• MCP Compliant: Full compatibility with the Model Context Protocol specification
• Multiple Transports: Supports both stdio (for Claude Code) and SSE transports
• ACID Compliant: Full transaction support with ACID guarantees
• Flexible Configuration: Environment variable based configuration
• Comprehensive Tools: Read, write, list, delete, watch, cursor scan, and transaction operations

Installation

pip install lmdb-mcp

Quick Start

As a CLI Tool

# Run with default settings
lmdb-mcp

# Run with custom database path and size
LMDB_PATH=/path/to/db LMDB_MAP_SIZE=5368709120 lmdb-mcp

With Claude Code

Add to your MCP settings file (.claude/mcp.json):

{
  "mcpServers": {
    "lmdb": {
      "command": "lmdb-mcp",
      "env": {
        "LMDB_PATH": "./my-data.db",
        "LMDB_MAP_SIZE": "1073741824"
      }
    }
  }
}

As a Python Library

from lmdb_mcp.core import LMDBMCP

# Create a simple LMDB wrapper
db = LMDBMCP("./my-data.db", map_size=1_048_576)

# Write and read data
db.write("key1", b"value1")
value = db.read("key1")

# List keys with prefix
keys = db.list_keys("prefix_")

# Clean up
db.close()

Configuration

The server can be configured using environment variables:

Variable	Description	Default
LMDB_PATH	Path to LMDB database file	./lmdb.db
LMDB_MAP_SIZE	Maximum database size in bytes	1073741824 (1GB)
LMDB_TRANSPORT	Transport type (stdio or sse)	stdio
LMDB_TOOL_PREFIX	Prefix for tool names	mcp__lmdb__

Available Tools

Basic Operations

• read: Read a value by key
• write: Write a value to a key
• list: List keys with optional prefix filtering
• delete: Delete a key

Advanced Operations

• watch: Watch for changes to keys matching a pattern
• cursor_scan: Scan a range of keys using a cursor
• transaction: Execute multiple operations atomically

Example Usage

Reading and Writing

# Write a value
await mcp__lmdb__write(key="user:123", value='{"name": "Alice", "age": 30}')

# Read a value
result = await mcp__lmdb__read(key="user:123")
# Returns: {"name": "Alice", "age": 30}

Listing Keys

# List all keys
all_keys = await mcp__lmdb__list()

# List keys with prefix
user_keys = await mcp__lmdb__list(prefix="user:")
# Returns: ["user:123", "user:456", ...]

Transactions

# Execute multiple operations atomically
operations = [
    {"type": "write", "key": "counter", "value": "1"},
    {"type": "write", "key": "status", "value": "active"},
    {"type": "read", "key": "counter"}
]
result = await mcp__lmdb__transaction(operations=json.dumps(operations))

Development

Setup

# Clone the repository
git clone https://github.com/nibzard/lmdb-mcp.git
cd lmdb-mcp

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src tests
ruff check --fix src tests

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=lmdb_mcp

# Run specific test
pytest tests/test_server.py::test_read_write

License

Apache License 2.0 - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Integration with APEX

This package was extracted from the APEX (Adversarial Pair Execution) project to provide a reusable LMDB-based MCP server. APEX uses this package for its agent memory management and state persistence.

Acknowledgments

Built on top of:

• LMDB - Lightning Memory-Mapped Database
• MCP - Model Context Protocol
• FastMCP - FastMCP framework