QMD MCP server

QMD MCP

QMD MCP packages QMD as a long-running Streamable HTTP MCP server. It provides QMD search and document retrieval together with bounded index-maintenance operations, without exposing arbitrary shell execution.

This is a community-maintained integration. It is not affiliated with, endorsed by, or officially maintained by the upstream QMD project.

Feedback and contributions

Use GitHub Issues for bug reports and feature requests and pull requests for proposed changes. See CONTRIBUTING.md for the development workflow, test requirements, and coding conventions. Security issues must follow the private process in SECURITY.md.

Release changes are recorded in CHANGELOG.md.

Quick start

The public Docker image is published on GitHub Container Registry (GHCR):

ghcr.io/x1pher/qmd-mcp:v0.1.7

The package is public, so Docker does not need a GitHub login to pull it.

For production deployments, use the immutable digest published in the corresponding GitHub Release rather than relying on the version tag alone.

The image supports linux/amd64 and linux/arm64. Each platform image retains only its matching QMD native llama runtime to keep the image bounded.

1. Create the directories

mkdir -p qmd/config qmd/content
cd qmd

Put the Markdown files you want QMD to index in content/.

2. Create config/index.yml

global_context: >-
  This is a local Markdown knowledge base. Search results are discovery evidence;
  read the source document before relying on a material claim.

collections:
  notes:
    path: /vault
    pattern: "**/*.md"
    ignore:
      - "archive/**"

  archive:
    path: /vault/archive
    pattern: "**/*.md"
    includeByDefault: false

  append-only-log:
    path: /vault/logs
    pattern: "history.md"
    includeByDefault: false
    embedding: false

path values refer to paths inside the container. The Compose example below mounts ./content at /vault.

embedding: false is a QMD MCP wrapper extension for collections that should remain lexical-only. The files are still indexed and available to explicit lexical (lex) searches, but they are excluded from embedding health and manual start_embed jobs. Use it for large append-only logs or other exact-lookup material where repeatedly rebuilding vectors adds cost without useful semantic recall.

3. Create compose.yml

services:
  qmd-mcp:
    image: ghcr.io/x1pher/qmd-mcp:v0.1.7
    container_name: qmd-mcp
    environment:
      QMD_FORCE_CPU: "1"
      QMD_REFRESH_INTERVAL_MINUTES: "15"
      QMD_REFRESH_INITIAL_DELAY_SECONDS: "120"
    ports:
      - "127.0.0.1:8181:8181"
    volumes:
      - ./content:/vault:ro
      - ./config:/config:ro
      - qmd-data:/data
    healthcheck:
      test:
        - CMD
        - node
        - -e
        - >-
          fetch('http://127.0.0.1:8181/health')
          .then(r=>process.exit(r.ok?0:1))
          .catch(()=>process.exit(1))
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

volumes:
  qmd-data:

The example binds the HTTP port to loopback only. If another container must call QMD MCP directly, attach both containers to a shared Docker network and use the QMD service name instead of exposing it broadly on the host.

QMDFORCECPU=1 gives a predictable CPU-only deployment. Remove it or set it to 0 if you deliberately want QMD to probe for supported acceleration.

4. Start the container

Shortened. The full README is on GitHub.