Skip to main content

MDDB · AI-native document database

The Knowledge Base
Your AI Agent Needs

Built-in MCP server, vector search, RAG, and hybrid retrieval. Plugs into Claude, ChatGPT, Cursor, Windsurf, and any MCP client — single ~32MB binary, zero config

97 MCP Tools v2.18.11 RAG-Ready UDS + mTLS Docker Ready
Download v2.18.11 View on GitHub
Works with
Claude ChatGPT Cursor Windsurf Ollama DeepSeek Manus Bielik.ai
Powers

daemonports.org — about 120,000 pages from the ports trees of five BSD systems in one collection, refreshed every 30 minutes; its public full-text search and autocomplete are served by MDDB on FreeBSD with ZFS. See its live memory and disk figures.

Why MDDB? #

One binary. Every protocol. AI-native from day one.

MDDB is an AI-native embedded document database written in Go, using BoltDB for storage. It accepts Markdown, plain text, HTML, PDF, DOCX, ODT, RTF, LaTeX, YAML, and Wikipedia XML dump documents, auto-converting everything to Markdown. All documents are stored with full revision history.

Core capabilities

  • Built-in MCP server with 97 tools — connects to Claude, Cursor, Windsurf, ChatGPT, Ollama, DeepSeek, Manus via stdio and HTTP transport
  • Geospatial search: R-tree and geohash indexes, radius and bounding-box queries, composable with full-text and vector search, optional postcode lookup
  • Transport options: TCP host:port or Unix Domain Socket (unix:/path.sock) for zero-network local deployments (PHP-FPM sidecars, cron, same-host panel)
  • TLS and mutual TLS (mTLS): user-supplied server cert/key, optional client CA bundle for certificate-based client authentication (MDDB_TLS_CLIENT_CA)
  • Vector/semantic search with 8 index algorithms: Flat (exact), HNSW, IVF, PQ, OPQ, SQ, SQ4, BQ, or algorithm: auto to let the server choose — OpenAI, Ollama, Cohere, Voyage AI embeddings or the offline lexical provider, with per-collection int8/int4 quantization (4-8x compression)
  • Full-text search with 8 modes (simple, boolean, phrase, wildcard, proximity, expression, range, fuzzy), TF-IDF, BM25, BM25F, PMISparse scoring, multi-language stemming (17 languages), typo tolerance, metadata pre-filtering
  • Hybrid search combining sparse (BM25) and dense (vector) with alpha blending or Reciprocal Rank Fusion
  • Zero-shot document classification using embedding cosine similarity
  • Custom MCP tools defined in YAML for domain-specific AI workflows
  • MCP toolsets: each agent or API key gets only the tool groups it needs (MDDB_MCP_TOOLSETS, per-key toolsets)
  • Confirmation of destructive MCP tools through MCP elicitation (MDDB_MCP_CONFIRM_DESTRUCTIVE=elicit|require)
  • Passages: search returns the path, line range and enclosing definition instead of whole documents
  • code_symbol: definitions, references, callers, callees and tests of a symbol in one call
  • mddb-cli autoindex . indexes a repository in one command; a second run rewrites only the files that changed
  • Retrieval gain: counts the tokens passages and chunks saved against whole documents
  • Images: alt text and captions are searchable; with Voyage or Cohere embeddings you can search by picture
  • LangChain / LangGraph: MddbVectorStore, MddbStore and the Deep Agents MddbBackend (langchain-mddb)
  • RAG pipeline: auto-embed on ingest, semantic retrieval, MCP exposure to LLMs
  • Memory RAG: conversational memory with session management, semantic recall, and summarization
  • Multi-protocol: HTTP/JSON REST API, HTTP/3, gRPC/Protobuf, GraphQL, Server-Sent Events, WebSocket streaming (via mddb-chat), MCP (Streamable HTTP / SSE / stdio)
  • Elasticsearch-compatible subset under /es (MDDB_ES_COMPAT=true): search, count, document and bulk calls for existing Elasticsearch clients
  • Multi-format upload: 20 file formats — .md, .txt, .html, .pdf, .docx, .odt, .rtf, .tex, .yaml, .xlsx, .ods, .csv, .tsv, .pptx, .odp, .epub, .eml, .mbox and more — with auto-conversion to Markdown
  • Corpus packs: a collection built once and installed read-only anywhere, without re-embedding or reindexing
  • Synced sources: a cron rule keeps a collection in step with a sitemap, a URL list or an S3 prefix
  • Wikipedia XML dump import: stream multi-GB MediaWiki dumps with wikitext-to-Markdown conversion, namespace filtering, batch processing
  • URL import: fetch and store documents from any URL
  • Document TTL with auto-expiry and background cleanup
  • Full revision history for every document
  • JWT authentication and RBAC authorization (opt-in)
  • Compliance-first (v2.9.15+): ISO 27001 / SOC 2 hardening built-in — audit log, AES-256-GCM at-rest encryption, HTTP+gRPC rate limiter, incident webhooks, and a single MDDB_PRODUCTION=true switch that refuses to boot without every control in place
  • Leader-follower replication with binlog streaming
  • Scheduled backups with retention and an S3 target; per-collection quotas, disk reserve and embedding budget
  • Behind a load balancer: trusted proxies (MDDB_TRUSTED_PROXIES) and PROXY protocol v1/v2 give rate limits and the audit log the real client IP
  • Automation: triggers, crons, webhooks, sentiment analysis, template variables
  • Multi-language support: same document key, multiple locales
  • Prometheus metrics, Grafana dashboard support and OpenTelemetry trace export
  • mddb-cli diagnose: a support bundle with no document content, queries, keys or IP addresses
  • ~32MB single binary, embedded BoltDB, zero external dependencies
  • Docker image: ~43MB compressed, Alpine-based, with health checks
  • Aggregations: metadata facets (value counts) and date histograms with optional pre-filtering
  • Per-collection storage backends: BoltDB (default), in-memory (ephemeral), S3/MinIO — configurable via API and web panel
  • Web admin panel (React-based) with REST/GraphQL API toggle
  • PHP and Python client libraries
MDDB
Claude
Cursor
ChatGPT
Windsurf
Ollama
AI Integration

97 Built-in MCP Tools

MCP 2026-07-28 and 2025-11-25 compliant. Tool annotations for auto-approve, 5 built-in prompts, completion, structured output, logging. Three transports: stdio, Streamable HTTP, SSE.

  • MCP 2026-07-28 + 2025-11-25
  • Tool Annotations
  • Prompts
  • Streamable HTTP
BM25TF-IDFPMISparse
+
FlatHNSWIVFPQOPQSQSQ4BQ
=
Hybrid RAG
Search

Hybrid Search Engine

Full-text with 8 search modes (simple, boolean, phrase, wildcard, proximity, expression, range, fuzzy) + vector search with 8 index types, or auto to let the server pick one for the collection. Multi-language stemming for 17 languages. Combine with alpha blending or Reciprocal Rank Fusion. Metadata pre-filtering, typo tolerance. Source code is searched as code and linked into a graph of calls, includes and references, from C and Go to Terraform and Kubernetes manifests. Alt text and captions of images are searchable; with Voyage or Cohere embeddings you can search by picture.

  • Vector Search
  • Full-Text (8 modes, 17 langs)
  • Hybrid RAG
  • Code Graph
  • Image Search
  • Zero-Shot Classification
RESTHTTP/JSON
gRPCProtobuf
GraphQLFlexible queries
WebSocketmddb-chat
/esElasticsearch subset
Protocols

Multi-Protocol Access

REST for easy debugging, gRPC for high-throughput pipelines, GraphQL for flexible frontend queries, and WebSocket streaming via mddb-chat for LLM chat pipelines. HTTP/3 when you turn it on, and an Elasticsearch-compatible subset under /es so an existing Elasticsearch client can search and write without a rewrite. All endpoints, one stack.

  • REST API
  • gRPC
  • GraphQL
  • WebSocket
  • HTTP/3
  • Elasticsearch subset
.md
.txt
.html
.pdf
.docx
.odt
.rtf
.tex
.yaml
.xlsx
.pptx
.epub
.eml
URL
Wiki XML
Markdown
Ingestion

Multi-Format Pipeline

Upload 20 file formats — documents, spreadsheets, slides, e-books and mail (.pdf, .docx, .xlsx, .csv, .pptx, .epub, .eml, .mbox, .odt, .rtf, .tex, .yaml and more) — import from any URL, keep a collection synced with a sitemap or an S3 prefix, or stream Wikipedia XML dumps (.xml.bz2). Everything auto-converts to Markdown. Background embedding worker indexes documents as they arrive.

  • 20 File Formats
  • Wikipedia Import
  • URL Import
  • Auto-Embed
  • TTL Expiry
autoindex .corpus packs
+
toolsetspassagescode_symbol
=
Fewer tokens per turn
Agents

Built for Coding Agents

mddb-cli autoindex . indexes a repository in one command; a second run rewrites only the files that changed. Give each agent or key only the tool groups it needs: search,code sends less than half the schema bytes of the full set. Passages return the path, line range and enclosing definition instead of whole documents, code_symbol returns a symbol's definitions, references, callers, callees and tests in one call, and retrieval gain counts the tokens that saved. With MDDB_MCP_CONFIRM_DESTRUCTIVE, a delete or restore waits for the human to confirm it through MCP elicitation. For LangChain and LangGraph: MddbVectorStore, MddbStore and the Deep Agents MddbBackend. Using MDDB from AI agents →

  • Toolsets
  • Passages
  • code_symbol
  • autoindex
  • Retrieval Gain
  • LangChain
Geosearch R-tree + geohash, radius/bbox
Unix Socket Zero-network local transport
mTLS Mutual TLS with client CAs
Revisions Full document history
Backups Scheduled, verified, S3 target
Quotas Documents, bytes, embedding budget
Corpus Packs Build once, install read-only
Behind a Proxy Trusted proxies, PROXY protocol
Replication Leader-follower binlog
Auth & RBAC JWT, API keys, per-collection
ISO 27001 / SOC 2 Audit log, AES-256-GCM, rate limiter, incident webhooks (v2.9.15+)
Automations Triggers, crons, webhooks
Aggregations Facets & histograms
Multi-Language Same key, many locales
Docker ~43MB Alpine image (compressed)
Zero Config Single binary, no deps
Storage Backends BoltDB, In-Memory, S3
Telemetry Prometheus, Grafana, OpenTelemetry
Diagnose Support bundle, no content, queries, keys or IPs

🎨 Web Admin Panel

Modern React-based UI for managing documents, users, and search with REST/GraphQL API toggle

MDDB Web Admin Panel
📊 Dashboard Real-time statistics and metrics
🔍 Search Metadata, vector, and full-text search
✏️ Editor Live markdown preview and editing
👥 Users User and group management
🔄 API Toggle Switch between REST and GraphQL
🔐 Auth JWT tokens and API keys
📦 Corpus Packs Install, build and remove packs; read-only collections say so
🩺 Diagnose Download the support bundle from the System page
⏱️ Backup & Sync Rules Cron rules for scheduled backups and synced sources
📈 Quota Usage One bar per limit: documents, bytes, vectors, embeddings
🧭 Search Plan Explain how a search ran: index, filter, candidates
🔒 Clear Refusals Permission and read-only refusals say why

Quick Start #

bash — docker 
# Run MDDB server
docker run -d \
  -p 11023:11023 \
  -p 11024:11024 \
  -v mddb-data:/app/data \
  tradik/mddb:latest

# Test the API
curl http://localhost:11023/health
bash — docker compose 
# Clone repository
git clone https://github.com/tradik/mddb.git
cd mddb

# Start the server, the web panel and the chat server
docker compose up -d

# Services available (bound to 127.0.0.1):
# - MDDB HTTP: http://localhost:11023
# - MDDB gRPC: localhost:11024
# - MCP (HTTP): http://localhost:9000/mcp
# - Web Panel: http://localhost:3000
# - Chat:      ws://localhost:11030/ws
bash — binary 
# Download binary
wget https://github.com/tradik/mddb/releases/download/v2.18.11/mddbd-v2.18.11-linux-amd64.tar.gz
tar -xzf mddbd-v2.18.11-linux-amd64.tar.gz

# Run server
./mddbd-v2.18.11-linux-amd64/mddbd

# Server starts on http://localhost:11023
bash — build from source 
# Clone repository
git clone https://github.com/tradik/mddb.git
cd mddb

# Build (server and CLI)
make build

# Run
./services/mddbd/mddbd

Download #

Latest Release

v2.18.11

Released: 30 October 2026

Linux AMD64 ~12MB Linux ARM64 ~12MB macOS AMD64 ~12MB macOS ARM64 ~12MB FreeBSD AMD64 ~12MB
📦 Debian/Ubuntu AMD64 (.deb) 📦 Debian/Ubuntu ARM64 (.deb) 📦 RedHat/CentOS AMD64 (.rpm) 📦 RedHat/CentOS ARM64 (.rpm) 🐧 Snap (Linux)

Package Managers

🍺 Homebrew macOS & Linux

brew tap tradik/tap
brew install tradik/tap/mddb
View Tap on GitHub →

🐧 Snap Linux

sudo snap install mddbd
sudo snap install mddb-cli
View on Snap Store →

🐳 Docker All platforms

docker pull tradik/mddb:latest
docker pull tradik/mddb:2.18.11
View on Docker Hub →

What's New in v2.18.11

  • One permission gate on every surface: with auth on, a key limited to one collection or one tenant can no longer read or write others over REST, gRPC, GraphQL or MCP, and admin on one collection no longer makes a global admin.
  • The real client IP behind a proxy: MDDB_TRUSTED_PROXIES, MDDB_CLIENT_IP_HEADER and PROXY protocol v1/v2. Behind a reverse proxy, set MDDB_TRUSTED_PROXIES when you upgrade, or every client shares the proxy's rate limit.
  • A result cap: a search returns at most MDDB_SEARCH_MAX_LIMIT results (1000 by default) and says "limitCapped": true when it lowered a request.
  • Elasticsearch-compatible subset: MDDB_ES_COMPAT=true mounts _search, _count, _doc and _bulk under /es, and refuses an unsupported clause by name.
  • Corpus packs and synced sources: install a collection read-only without re-embedding it, or keep one in step with a sitemap, a URL list or an S3 prefix.
  • Query decomposition and mddb-cli diagnose: queryDecomposition: "auto" searches a question with several needs part by part; the diagnose bundle is a tar.gz without user data to attach to an issue.
View Full Changelog →

Documentation #

Getting Started

Search & AI

Security & Operations

Protocols & Advanced

Code Examples #

bash — mddb 
# Add document with TTL (expires in 1 hour)
curl -X POST http://localhost:11023/v1/add \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "key": "hello-world",
    "lang": "en_US",
    "ttl": 3600,
    "meta": {
      "category": ["tutorial"],
      "author": ["John Doe"]
    },
    "contentMd": "# Hello World\n\nWelcome to MDDB!"
  }'

# Import directly from URL
curl -X POST http://localhost:11023/v1/import-url \
  -d '{"collection":"docs", "url":"https://example.com/guide.md", "lang":"en_US"}'
bash — vector search 
# Semantic search - flat (exact, default)
curl -X POST http://localhost:11023/v1/vector-search \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "kb",
    "query": "how do I cancel my subscription?",
    "topK": 5,
    "threshold": 0.7,
    "includeContent": true
  }'

# HNSW - fast approximate nearest neighbor
curl -X POST http://localhost:11023/v1/vector-search \
  -d '{"collection":"kb", "query":"refund", "topK":5, "algorithm":"hnsw"}'

# IVF - clustered search for large collections
curl -X POST http://localhost:11023/v1/vector-search \
  -d '{"collection":"kb", "query":"refund", "topK":5, "algorithm":"ivf"}'

# PQ - compressed, memory-efficient search
curl -X POST http://localhost:11023/v1/vector-search \
  -d '{"collection":"kb", "query":"refund", "topK":5, "algorithm":"pq"}'

# auto - the server picks the index per query: vector count, built indexes, filter
curl -X POST http://localhost:11023/v1/vector-search \
  -d '{"collection":"kb", "query":"refund", "topK":5, "algorithm":"auto"}'
bash — full-text search 
# Simple search with BM25 scoring
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "markdown database tutorial",
    "limit": 10,
    "algorithm": "bm25"
  }'

# Boolean search (AND, OR, NOT, +required, -excluded)
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "rust AND performance NOT garbage",
    "mode": "boolean"
  }'

# Phrase search — exact word sequence
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "\"machine learning\"",
    "mode": "phrase"
  }'

# Proximity search — terms within 5 words
curl -X POST http://localhost:11023/v1/fts \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "blog",
    "query": "\"database performance\"~5",
    "mode": "proximity",
    "distance": 5
  }'
python3 — mddb client 
from mddb import MDDB

# TCP connection
db = MDDB.connect('localhost:11023', 'write').collection('kb')

# Unix Domain Socket (MDDB 2.9.14+, zero-network local transport)
# db = MDDB.connect('unix:/tmp/mddb.sock', 'write').collection('kb')

# Add document
db.add('faq', 'en_US', {'category': ['billing']}, '# Billing FAQ\n\nCancel in Settings.')

# Vector search (RAG pipeline step 1)
results = db.vector_search('how to cancel?', top_k=3, include_content=True)

# Full-text search
results = db.fts_search('billing refund', limit=10)

# Webhooks
db.register_webhook('https://app.com/hook', ['doc.added'], 'kb')

# Import from URL
db.import_url('https://example.com/docs.md', 'en_US')

# TTL
db.set_ttl('temp-key', 'en', 3600)  # expires in 1h
php — mddb client 
<?php
require_once 'mddb.php';

// TCP connection
$db = mddb::connect('localhost:11023', 'write');

// Unix Domain Socket (MDDB 2.9.14+)
// $db = mddb::connect('unix:/tmp/mddb.sock', 'write');

// Add document
$db->collection('blog')->add('hello', 'en_US', ['category' => ['tutorial']], '# Hello');

// Vector search
$results = $db->collection('kb')->vectorSearch('cancel subscription', 5, 0.7, true);

// Full-text search
$results = $db->collection('blog')->ftsSearch('database tutorial', 10);

// Webhooks
$db->registerWebhook('https://app.com/hook', ['doc.added', 'doc.updated']);

// Import from URL
$db->collection('docs')->importUrl('https://example.com/post.md', 'en_US');

// TTL
$db->collection('cache')->setTtl('temp', 'en', 3600);
json — mcp.json 
# Docker (Easiest) - for Windsurf / Claude Desktop
# Configure ~/.windsurf/mcp.json:
{
  "mcpServers": {
    "mddb": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "-v", "mddb-data:/app/data",
        "-e", "MDDB_MCP_STDIO=true",
        "tradik/mddb:latest"
      ]
    }
  }
}

# MCP provides 97 built-in tools including:
# - add_document, search_documents, semantic_search
# - full_text_search, hybrid_search, cross_search
# - classify_document, find_duplicates
# - geo_search, geo_within, geo_encode, geo_decode, geo_stats
# - automation, webhooks, schemas, backups
# - collection config, revisions, aggregate, and more

🔄 Leader-Follower Replication #

Scale reads horizontally with binlog-based streaming replication. A single leader handles writes and streams transactions in real-time to read-only followers via gRPC.

graph LR C[Clients] -->|Writes/Reads| L[Leader] C -->|Reads| F1[Follower 1] C -->|Reads| F2[Follower 2] L -->|gRPC binlog stream| F1 L -->|gRPC binlog stream| F2
Read Replication Guide

Community & Support #

🐙

GitHub

Source code, issues, and discussions
🐛

Report Issues

Bug reports and feature requests
💬

Discussions

Ask questions and share ideas
🤝

Contributing

Help improve MDDB