QMD

QMD provides a containerized MCP server that enables hybrid search over your local markdown knowledge base. It works with MCP-compatible agents and offers both local STDIO and HTTP transport modes, giving you fast, persistent search across your notes with minimal setup.

How to use

You interact with QMD through an MCP client. In STDIO mode, Claude Code or other local MCP agents launch a fresh container for each tool call and receive results back for indexing, searching, or retrieving documents. In HTTP mode, you connect to a persistent HTTP/SSE endpoint to perform all MCP operations over the network. Start by configuring your client to point at the QMD MCP server in the mode you prefer, then perform ingestion, queries, and document retrieval as you work with your notes.

How to install

Prerequisites are Docker and Docker Compose installed on your machine. You will also need an embedding API key for vector searches.

Choose STDIO mode for local development with Claude Code or other MCP agents. Follow these steps in order:

# 1. Build the Docker image
docker compose build

# 2. Run the automated setup script
./setup-qmd-mcp.sh

# 3. Restart Claude Code

# 4. Start using QMD!
# In Claude Code: "Please index my markdown files using qmd"

Configuration and deployment notes

QMD supports two deployment modes. STDIO mode uses stateless, short-lived containers with a persistent named volume to store the index and embeddings. HTTP mode runs a long-lived container accessible via a host port, with the knowledge base mounted from the host.

To configure STDIO mode manually, you would add a MCP server entry that runs Docker and invokes the QMD container with the appropriate arguments. The setup script automates this configuration and ensures the correct MCP settings are written to your Claude client.

Environment variables you will typically configure include your embedding API key, the embedding model, and paths to your knowledge base and cache. You may also configure transport type, port, and chunking parameters for indexing and search.

Volume persistence and performance

QMD uses a named Docker volume to persist the SQLite database and embeddings across container runs. This ensures fast search without re-indexing every time you query, and it allows data to survive restarts and system reboots.

Your markdown notes are mounted read-only into the container in STDIO mode to prevent accidental modification, while the cache directory holds the persistent index and embeddings.

Tools and actions you can perform

QMD exposes a set of MCP tools that you can call through your MCP client to manage and search your knowledge base.

Troubleshooting

If the MCP tools do not appear in Claude Code, verify that your MCP configuration exists and is correctly structured, then restart the client after changes. If embeddings are not enabled, check that the embedding API key is correctly provided to the container and that the key is valid. For a fresh start, ensure the named cache volume exists and contains the database. If containers linger unexpectedly, confirm you are using the --rm flag in STDIO mode cartridges and remove stale containers if needed.

Notes on security and usage

Mount your notes as read-only in STDIO mode to prevent modifications. In HTTP mode, ensure access is restricted to trusted clients and consider network security practices for exposing a persistent endpoint.

Example workflows

Ingestion: After adding or updating markdown files, trigger the ingestion pipeline to index changes. Then perform hybrid searches to locate relevant content, retrieve full documents, and cross-reference information across your notes.

Final reminders

If you need to re-index everything, use the ingestion tool with a force option. For quick retrieval, rely on the cached embeddings and the fast keyword search offered by the underlying FTS5 database in the volume.

Tools overview

qmd_query — Hybrid search combining BM25 keyword matching with vector semantic search.

qmd_vsearch — Vector-only semantic search for conceptual similarity.

qmd_refresh_index — Trigger ingestion to index or re-index files.

qmd_get — Retrieve the full content of a specific file.

qmd_list — List all indexed files in the knowledge base.

Glossary of environment variables

OPENROUTER_API_KEY: API key for embeddings.

QMD_EMBEDDING_MODEL: Embedding model name to use.

QMD_KB_PATH: Path to your markdown notes on the host.

QMD_CACHE_PATH: Path for SQLite DB and embeddings on the host.

MCP_TRANSPORT: Transport mode, either stdio or http.

QMD_PORT: HTTP server port when using HTTP mode.

Available tools

qmd_query

Hybrid search combining BM25 keyword matching with vector semantic search.

qmd_vsearch

Vector-only semantic search for conceptual similarity.

qmd_refresh_index

Trigger ingestion to index or re-index files.

qmd_get

Retrieve the full content of a specific file.

qmd_list

List all indexed files in the knowledge base.