M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
Q

QMD MCP Server

Official
A local hybrid search engine for Markdown knowledge bases.
How to install ↓ Compare GitHub source repository ↗
Category
Dev Tools #176 of 438
Stars
★ 30.3k Very popular
Transport
stdio (local process) · Streamable HTTP
Runtime
Node.js 22+ · Bun 1.0.0+
Credentials
No credential needed
License
MIT
Last commit
Tools
4
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.

Strongest · Documentation 15/20 Weakest · Maintenance 8/20

Reliability
9/20
Security and permissions
11/20
Maintenance
8/20
Documentation
15/20
Setup experience
13/20
Why each score
Reliability 9/20
The README explicitly lists the MCP tools query, get, multi_get, and status with parameters, and documents both stdio and HTTP transport, index dependencies, and several failure boundaries, making the happy path plausible. However, no cached manifest, source files, CI, or committed tests are provided; unknown parameters are silently ignored, and first-run model downloads and local index state can produce hard-to-diagnose failures. Static review evidence is therefore insufficient, and the score remains below the 12-point ceiling.
Security and permissions 11/20
The default stdio mode operates on locally configured index directories, while project-local external paths, update commands, and custom models are trust-gated. HTTP binds to localhost by default and includes Origin/Host checks, with the boundary documented. However, HTTP has no authentication; binding to 0.0.0.0 skips host validation, environment variables can disable checks, and configured update commands execute through bash. In MCP/CI contexts, gated fields are skipped rather than interactively approved. No credential theft or malicious default is evidenced, but authentication, least privilege, and remote exposure controls are incomplete, so points are deducted.
Maintenance 8/20
The project states an MIT license and provides a repository, CHANGELOG reference, and explicit configuration and model update paths, indicating some maintenance foundation. The supplied material does not provide release history, commit cadence, dependency update policy, CI evidence, vulnerability response channel, or maintainer commitments. Star and issue counts are discovery signals only and add no points, so the score is conservative.
Documentation 15/20
The README covers installation, client configuration, stdio/HTTP transport, tool parameters, output formats, indexing, models, environment variables, edge behavior, trust controls, limitations, and examples. It explicitly discloses the unauthenticated HTTP endpoints, model downloads, and resource requirements. Deductions reflect the missing manifest, absence of verifiable source/test evidence, naming differences between some SDK and MCP examples, and limited evidence for cost, troubleshooting, and version compatibility.
Setup experience 13/20
npm, Bun, npx/bunx installation paths are provided, along with Claude Desktop and Claude Code configuration examples. Runtime, SQLite, model download, and HTTP endpoint requirements are also described, so the connection path is clear. Deductions reflect the Node 22/Bun requirement, possible Homebrew SQLite prerequisite on macOS, roughly 2 GB of first-use model downloads, and extra indexing/embedding steps. Compatibility with other mainstream clients and CI verification are not evidenced.

Static review · not runListed 2026-08-14

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesConnects to a database

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

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

Setup

Before you start

Runtime：Node.js 22+ · Bun 1.0.0+

Other optional settings (11)
QMD_EMBED_MODEL optional HuggingFace GGUF URI overriding the default embedding model, useful for multilingual (CJK) corpora; run qmd embed -f after changing it.
QMD_ALLOWED_ORIGINS optional Comma-separated extra Origins accepted by the HTTP transport; set to * to disable the check.
QMD_ALLOWED_HOSTS optional Comma-separated extra Host header values accepted by the HTTP transport; re-enables host checking when --host 0.0.0.0 is used.
QMD_HOST optional Overrides the HTTP server bind address (default localhost).
QMD_CONFIG_DIR optional Overrides the config directory (default ~/.config/qmd) where index.yml lives.
QMD_LLAMA_GPU optional Forces a llama.cpp GPU backend (metal/vulkan/cuda) or disables GPU with false.
QMD_FORCE_CPU optional Set to 1/true to force CPU mode; equivalent to --no-gpu.
QMD_EMBED_PARALLELISM optional Overrides embedding/reranking context parallelism (1-8); defaults to 1 on Windows CUDA.
QMD_EDITOR_URI optional Editor URI template for clickable terminal result links, e.g. vscode://file/{path}:{line}:{col}.
QMD_TRUST_LOCAL_CONFIG optional Set to 1 to allow unattended (CI/MCP) adoption of gated fields in project-local .qmd/index.yml.
QMD_TRUST_UPDATE_HOOKS optional Set to 1 to allow unattended (CI/MCP) execution of update commands from project configs.

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"]}}}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "qmd": {
      "command": "qmd",
      "args": [
        "mcp"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add qmd -- qmd mcp

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After installing and running qmd embed to index your collections, check that the tools query, get, multi_get and status appear in your client's tool list, then call status to confirm the connection.

Troubleshooting

  1. Verify Node.js is version 22 or later, or Bun is version 1.0.0 or later
  2. Add collections with qmd collection add, run qmd update, and run qmd embed before semantic search
  3. On macOS, install Homebrew SQLite if SQLite extension support fails
  4. 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
  5. Use the collections array to scope MCP queries; a singular collection parameter is silently ignored
  6. Check model downloads, GPU/CPU settings, and qmd status or qmd doctor output

Things to try

Once connected, you can ask your AI assistant things like:

  • Use the query tool to search my notes for 'authentication flow' and limit results to 5
  • Fetch the full content of docs/api-reference.md with the get tool
  • Use multi_get to batch-read all documents matching journals/2025-05*.md
  • Run status to show index health and my configured collections

Tools 4

query read-only
Runs lexical, vector, and HyDE sub-queries, combining results with RRF and local LLM reranking.
get read-only
Retrieves one document by path, document ID, or line range.
multi_get read-only
Retrieves multiple documents by glob pattern, comma-separated paths, or document IDs.
status read-only
Reports index health and collection information.

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 Desktop
Claude Code

Listed from the project's documentation, not tested by this site.

Overview

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.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 62.9k · Tools 2 Compare with this →
Compare with other MCP servers

Source revision 93d211f9ef4a Data synced 2026-10-12 Read the FMRS scoring method