LMDB MCP Server

A high-performance TypeScript MCP (Model Context Protocol) server for LMDB (Lightning Memory-Mapped Database) operations. Built with the official MCP SDK and the lmdb npm package for production-ready, ACID-compliant key-value storage.

Features

• High Performance: Built on LMDB for lightning-fast read/write operations (microsecond-level latency)
• Full MCP Support: Complete implementation of the Model Context Protocol with stdio transport
• ACID Compliant: Full transaction support with atomicity, consistency, isolation, and durability
• Schema System: Optional JSON Schema validation for structured data with namespaces and collections
• Type Safe: Written in TypeScript with full type definitions
• Collection Management: High-level API for managing records in namespaces/collections
• Range Queries: Efficient cursor-based iteration and prefix scanning
• Multiple Encodings: Support for MessagePack (default), JSON, string, and binary encodings

Architecture

lmdb-mcp/
├── src/
│   ├── core/           # LMDB client, transaction wrapper
│   │   ├── client.ts   # Main LMDB client interface
│   │   ├── transaction.ts  # Transaction builder and wrapper
│   │   └── types.ts    # Core type definitions
│   ├── schema/         # Schema registry, type system
│   │   ├── registry.ts # Schema registration and validation
│   │   ├── collection.ts  # High-level collection operations
│   │   └── types.ts    # Schema type definitions
│   ├── tools/          # MCP tool definitions
│   │   ├── handlers.ts # Tool implementation handlers
│   │   ├── definitions.ts # Tool schemas for MCP
│   │   └── types.ts    # Tool type definitions
│   ├── transports/     # stdio, SSE, HTTP
│   │   └── stdio.ts    # STDIO transport implementation
│   ├── index.ts        # Main exports
│   └── cli.ts          # CLI entry point
├── package.json
├── tsconfig.json
└── README.md

Installation

# Using bun (recommended)
bun add lmdb-mcp

# Using npm
npm install lmdb-mcp

# Using yarn
yarn add lmdb-mcp

Quick Start

As an MCP Server with Claude Code

Add to your Claude MCP settings (.claude/mcp.json or equivalent):

{
  "mcpServers": {
    "lmdb": {
      "command": "bun",
      "args": ["run", "/path/to/lmdb-mcp/src/cli.ts"],
      "env": {
        "LMDB_PATH": "./my-data.db",
        "LMDB_MAP_SIZE": "1073741824"
      }
    }
  }
}

Command Line Usage

# Run with default settings (creates ./lmdb.db)
bun run src/cli.ts

# Run with custom database path
bun run src/cli.ts --path /data/mydb.db

# Run with larger map size (2GB)
bun run src/cli.ts --map-size 2147483648

# Run with JSON encoding
bun run src/cli.ts --encoding json

# Show help
bun run src/cli.ts --help

Programmatic Usage

import { createServer } from 'lmdb-mcp';

// Create and start the server
const server = await createServer({
  dbPath: './my-data.db',
  mapSize: 1024 * 1024 * 1024, // 1GB
  encoding: 'msgpack',
});

await server.start();

Configuration

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_MAX_DBS | Maximum number of databases | 12 | | LMDB_ENCODING | Database encoding type | msgpack |

CLI Options

Options:
  -p, --path <path>        Path to LMDB database
  -m, --map-size <bytes>   Maximum database size in bytes
  -d, --max-dbs <number>   Maximum number of databases
  -e, --encoding <type>    Encoding: msgpack, json, string, binary
  -h, --help               Show help message
  -v, --version            Show version

Available MCP Tools

Basic KV Operations

lmdb_get

Get a value by key.

{
  "key": "user:123"
}

lmdb_put

Store a value.

{
  "key": "user:123",
  "value": {"name": "Alice", "age": 30}
}

lmdb_delete

Delete a key.

{
  "key": "user:123"
}

lmdb_exists

Check if a key exists.

{
  "key": "user:123"
}

Range and Query Operations

lmdb_list

List keys with optional prefix filtering.

{
  "prefix": "user:",
  "limit": 100
}

lmdb_get_range

Get a range of key-value pairs.

{
  "start": "user:100",
  "end": "user:200",
  "limit": 50
}

Transaction Operations

lmdb_transaction

Execute multiple operations atomically.

{
  "operations": [
    {"type": "put", "key": "counter", "value": 1},
    {"type": "get", "key": "counter"},
    {"type": "delete", "key": "temp"}
  ]
}

Statistics

lmdb_stats

Get database statistics.

{}

Schema Operations

lmdb_register_schema

Register a schema for a collection.

{
  "namespace": "users",
  "collection": "profiles",
  "schema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "email": {"type": "string"},
      "age": {"type": "number"}
    },
    "required": ["name", "email"]
  },
  "description": "User profile data"
}

lmdb_get_schema

Get a collection schema.

{
  "namespace": "users",
  "collection": "profiles"
}

lmdb_list_collections

List collections in a namespace.

{
  "namespace": "users"
}

lmdb_list_namespaces

List all namespaces.

{}

Collection Record Operations

lmdb_insert_record

Insert a record into a collection.

{
  "namespace": "users",
  "collection": "profiles",
  "data": {
    "name": "Alice",
    "email": "[email protected]",
    "age": 30
  }
}

lmdb_get_record

Get a record by ID.

{
  "namespace": "users",
  "collection": "profiles",
  "id": "1234567890-abc123"
}

lmdb_list_records

List records in a collection.

{
  "namespace": "users",
  "collection": "profiles",
  "limit": 100,
  "offset": 0
}

lmdb_update_record

Update a record.

{
  "namespace": "users",
  "collection": "profiles",
  "id": "1234567890-abc123",
  "data": {
    "age": 31
  },
  "upsert": false
}

lmdb_delete_record

Delete a record.

{
  "namespace": "users",
  "collection": "profiles",
  "id": "1234567890-abc123"
}

Namespace Pattern

This server follows the namespace pattern from the Python lmdb-mcp reference:

• Records: /{namespace}/{collection}/{id}
• Metadata: /{namespace}/metadata/{collection}
• Schema: /{namespace}/schema/{collection}
• Index: /{namespace}/index/{collection}/{field}/{value}
• Stats: /{namespace}/stats

Development

Setup

# Clone the repository
git clone <repository-url>
cd lmdb-mcp

# Install dependencies
bun install

# Build the project
bun run build

Running in Development

# Run the CLI directly
bun run dev

# Or run with tsx
tsx src/cli.ts --path ./test.db

Building

bun run build

This compiles TypeScript to JavaScript in the dist/ directory.

Type Checking

bun run lint

API Reference

LMDBClient

The main client for database operations.

import { LMDBClient } from 'lmdb-mcp';

const client = new LMDBClient({
  path: './my-db.db',
  mapSize: 1024 * 1024 * 1024,
});

await client.open();

// Basic operations
client.get('key');
await client.put('key', { value: 'data' });
await client.delete('key');
client.exists('key');

// Range queries
client.getRange({ start: 'a', end: 'z', limit: 100 });
client.getKeys({ prefix: 'user:' });

// Transactions
await client.transaction([
  { type: 'put', key: 'a', value: 1 },
  { type: 'put', key: 'b', value: 2 },
]);

SchemaRegistry

Manage collection schemas.

import { SchemaRegistry } from 'lmdb-mcp';

const registry = new SchemaRegistry(client);

// Register a schema
await registry.registerSchema({
  name: 'profiles',
  namespace: 'users',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
    },
  },
  indexes: [],
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString(),
});

// Get schema
const schema = registry.getSchema('users', 'profiles');

// List collections
const collections = registry.listCollections('users');

Collection

High-level collection operations.

import { Collection } from 'lmdb-mcp';

const collection = new Collection(client, registry, 'users', 'profiles');

// Insert record
const id = await collection.insert({ name: 'Alice', email: '[email protected]' });

// Get record
const record = collection.get(id);

// Update record
await collection.update(id, { age: 31 });

// List records
const records = collection.list({ limit: 100 });

// Delete record
await collection.delete(id);

Error Handling

All operations use typed error classes:

• LMDBError: Base error class
• TransactionError: Transaction-related errors
• ValidationError: Schema validation errors

import { LMDBError, TransactionError } from 'lmdb-mcp';

try {
  await client.put('key', 'value');
} catch (error) {
  if (error instanceof TransactionError) {
    console.error('Transaction failed:', error.message);
  } else if (error instanceof LMDBError) {
    console.error('LMDB error:', error.code, error.message);
  }
}

Performance Considerations

• Read Performance: LMDB reads are synchronous and typically complete in sub-microsecond time
• Write Performance: Writes are batched and executed asynchronously for optimal throughput
• Memory Usage: LMDB is memory-mapped, so data access doesn't require explicit copying
• Compression: Enable compression for large databases to improve caching

License

MIT

Acknowledgments

Built with:

• LMDB - Lightning Memory-Mapped Database
• lmdb-js - Node.js LMDB bindings
• Model Context Protocol - MCP SDK
• Inspired by lmdb-mcp (Python)