Guide · Open source

How to use qmd: install, index your notes and search locally

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

qmd is a free, MIT-licensed command-line search engine that indexes your markdown notes, meeting transcripts and documentation on your own machine. This guide shows you how to install it, point it at your folders, run keyword and natural-language searches, and connect it to AI agents such as Claude Desktop or Claude Code. It is aimed at readers comfortable with a terminal who want local document search.

QMDtobi/qmd · ★ 30.8k · MIT Install options & downloads

Quick start

1Install qmd. Run npm install -g @tobilu/qmd or bun install -g @tobilu/qmd. You need Node.js or Bun.
2Add a collection. Point qmd at a folder of markdown files with qmd collection add and give it a name using --name.
3Add context. Describe each collection with qmd context add so results carry useful background.
4Generate embeddings. Run qmd embed to create embeddings for semantic search.
5Run a search. Try qmd search for keywords, qmd vsearch for meaning, or qmd query for hybrid search with reranking.
6Optionally connect via MCP. Run qmd mcp and add the server entry to your Claude Desktop or Claude Code configuration.

Install qmd with npm or Bun

qmd is installed with a package manager and needs Node.js or Bun. Install it globally with npm or Bun, then run the qmd command from your terminal.

If you do not want a global install, the README also shows running it directly with npx or bunx.

Requires Node.js or Bun
Global install with npm or Bun
Run without installing using npx or bunx

npm install -g @tobilu/qmd
# or
bun install -g @tobilu/qmd

Add collections for your notes and documents

A collection is a named folder that qmd indexes. Add one for each area you want to search, giving it a name with --name.

Each collection can also get a short piece of context. The README says this context is returned alongside matching sub-documents, which helps AI agents choose the right documents. It is described as a tree, so context is organised hierarchically.

qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd context add qmd://notes "Personal notes and ideas"

Generate embeddings for semantic search

Keyword search works on indexed text directly. For semantic search by meaning, run qmd embed to generate embeddings. Semantic search and the best-quality hybrid search depend on these embeddings and on local GGUF models run through node-llama-cpp.

Keyword search: qmd search
Meaning-based search: qmd vsearch
Hybrid search with reranking: qmd query

qmd embed

Search by keyword or natural language

Pick the search command that fits the question. qmd search is fast keyword search. qmd vsearch matches by meaning. qmd query combines full-text search, vector search and LLM re-ranking, and the README calls it the best quality option.

You can limit a search to one collection with -c, and export all matches as a file list for an agent with --all --files and --min-score.

qmd search "project timeline" for fast keyword matches
qmd vsearch "how to deploy" for semantic matches
qmd query "quarterly planning process" for hybrid search with reranking
qmd search "API" -c notes to search one collection

qmd search "project timeline"
qmd vsearch "how to deploy"
qmd query "quarterly planning process"
qmd search "API" -c notes

Retrieve documents and use output for agents

Search results show a docid you can use to fetch a document. Use qmd get with a path or a docid prefixed with #, and qmd multi-get with a glob pattern to fetch several files.

For scripts and agents, the README says --json and --files output formats are designed for agentic workflows.

Fetch by path or docid with qmd get
Fetch several files with qmd multi-get and a glob
Use --json for structured results
Use --full to retrieve full document content

qmd get "meetings/2024-01-15.md"
qmd get "#abc123"
qmd multi-get "journals/2025-05*.md"
qmd search "authentication" --json -n 10

Connect qmd to Claude Desktop or Claude Code via MCP

qmd includes an MCP (Model Context Protocol) server, started with qmd mcp. For Claude Desktop, add a qmd entry under mcpServers in claude_desktop_config.json. For Claude Code, the README recommends installing the plugin, or you can configure MCP manually in ~/.claude/settings.json.

By default the server uses stdio, launched by each client. For a shared long-lived server, the README describes an HTTP transport on localhost:8181 by default. The HTTP endpoints are unauthenticated, so keep the server on localhost unless you put your own authentication in front of it.

Tools exposed: query, get, multi_get, status, metadata
Default stdio transport starts a subprocess per client
HTTP transport is available with qmd mcp --http

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

What people use it for

Searching years of personal markdown notes by keyword or by meaning
Finding decisions and action items across meeting transcripts
Giving an AI agent document retrieval through the qmd MCP server
Exporting matching file lists with --json or --files for a script to process

Frequently asked questions

Is qmd free to use?

qmd is released under the MIT licence, according to the project's listing. The MIT licence generally allows free use, modification and redistribution, but check the licence file in the repository for the full terms.

What do I need to run qmd?

You need Node.js or Bun to install it. Embeddings and reranking rely on local LLM models run through node-llama-cpp with GGUF models, so machines that cannot run local LLM models will not get the full feature set.

Does qmd send my documents to the cloud?

The README says qmd runs all models locally via node-llama-cpp with GGUF models, and it is built to keep documents on your own machine. Review the project's documentation if you have specific data-handling requirements.

How is qmd different from ripgrep?

ripgrep is a fast text search tool for matching patterns. qmd adds BM25 full-text search, vector semantic search and LLM re-ranking, so you can search by meaning as well as by keyword, and it offers an MCP server for agents.

Can I use qmd with a graphical app?

No. The README describes a command-line tool and MCP server, not a graphical app. If you need a GUI, tools such as Obsidian search may suit you better.

Is it safe to run qmd on a network server?

The README says the HTTP endpoints are unauthenticated and the server binds to localhost by default. It warns that --host 0.0.0.0 skips the host check, so put your own authentication in front of any server reachable off-host and do not treat it as a multi-user server.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

qmd suits people with many markdown notes or meeting transcripts who want local search, and developers building agent workflows that need document retrieval through MCP. It is a poor fit if you need a graphical app, a machine that cannot run local LLM models, or a multi-user or internet-facing server. For simple exact-match search, ripgrep may be enough.

Install options & downloads