Best for
- Users who want documents and model processing to remain local
- Individuals and teams with Markdown documents, meeting records, or code documentation
- Agent workflows that benefit from combined keyword and semantic search
Q
QMD MCP Server
Official
A local hybrid search engine for Markdown knowledge bases.
GitHub source repository ↗
56FMRS · C
QMD is a capable local MCP search server for Markdown knowledge bases, combining keyword, semantic, and hybrid reranked retrieval with single-document and batch retrieval. It suits local agent workflows but requires local model execution, indexing storage, and file-read permissions; its HTTP mode does not provide authentication.
QMD is an on-device document search engine for Markdown notes, meeting transcripts, documentation, and knowledge bases. It combines BM25 full-text search, vector semantic search, and local LLM reranking, exposing query, document retrieval, batch retrieval, and index-status tools through MCP.
Tools
query
Runs lexical, vector, and HyDE sub-queries, combining results with RRF and local LLM reranking.
get
Retrieves one document by path, document ID, or line range.
multi_get
Retrieves multiple documents by glob pattern, comma-separated paths, or document IDs.
status
Reports index health and collection information.
Setup
Install Node.js 22 or later, run npm install -g @tobilu/qmd, add the configuration in install_config to the Claude Desktop configuration file, and restart the client. QMD downloads and caches local GGUF models on first use of semantic or hybrid search. Alternatively, run qmd mcp --http and connect an MCP client to http://localhost:8181/mcp.
claude_desktop_config.json
{"mcpServers":{"qmd":{"command":"qmd","args":["mcp"]}}}
Fit and risk
Not for
- Users seeking hosted cloud search, remote knowledge-base synchronization, or built-in authentication
- Environments without resources to run local models or download GGUF files
- Use cases involving files outside configured collections or unsupported indexed content
Required permissions
- Read access to configured collection files for indexing and document retrieval
- Write access to local QMD configuration, cache, SQLite index, and model-cache locations
- Network access to download GGUF models from HuggingFace on first use; collection update hooks may also execute configured shell commands
Risks and side effects
- HTTP endpoints are unauthenticated by default; add an authentication layer before binding the server to a non-local address
- The index may contain personal notes, meeting transcripts, or internal documentation, so local index files and HTTP access require protection
- Configured collection update commands execute through bash in the collection directory and can abort subsequent updates on failure
- Custom project-local configuration can reference paths outside the project or custom models; untrusted fields are skipped in non-interactive environments
Troubleshooting
- Verify Node.js is version 22 or later, or Bun is version 1.0.0 or later
- Add collections with qmd collection add, run qmd update, and run qmd embed before semantic search
- On macOS, install Homebrew SQLite if SQLite extension support fails
- For HTTP connection issues, check the port, bind address, Origin, and Host validation; configure QMD_ALLOWED_ORIGINS or QMD_ALLOWED_HOSTS for expanded access and provide your own authentication
- Use the collections array to scope MCP queries; a singular collection parameter is silently ignored
- Check model downloads, GPU/CPU settings, and qmd status or qmd doctor output
Use cases
Searching personal Markdown notes and knowledge bases
Retrieving meeting transcripts and project documentation
Providing structured local document retrieval for AI agents
Fetching full documents or selected line ranges by path or document ID
Supported clients
Claude DesktopFull support
Claude CodeFull support