Skip to main content
Start the MCP (Model Context Protocol) server to expose QMD’s search and retrieval capabilities to AI agents and IDEs.

​
Usage

# Stdio transport (default, for Claude Desktop/Cline/etc)
qmd mcp

# HTTP transport (advanced)
qmd mcp --http [--port PORT]

# Background daemon (HTTP only)
qmd mcp --http --daemon [--port PORT]

# Stop daemon
qmd mcp stop

​
Transport Modes

​
Stdio (default)

Communicates via stdin/stdout. Used by:
  • Claude Desktop — Configure in claude_desktop_config.json
  • Cline — Add to MCP servers list
  • Other MCP clients — Any client supporting stdio transport
qmd mcp
Runs in foreground, logs to stderr. Stop with Ctrl+C.

​
HTTP

Exposes MCP over HTTP/SSE. Useful for:
  • Web-based clients
  • Custom integrations
  • Remote access
# Start on default port 8181
qmd mcp --http

# Custom port
qmd mcp --http --port 9000
Runs in foreground. Access at http://localhost:8181/mcp

​
HTTP Daemon

Runs HTTP server in background: 
# Start daemon
qmd mcp --http --daemon
# Started on http://localhost:8181/mcp (PID 12345)
# Logs: /home/user/.cache/qmd/mcp.log

# Stop daemon
qmd mcp stop
# Stopped QMD MCP server (PID 12345).
Logs written to ~/.cache/qmd/mcp.log PID stored in ~/.cache/qmd/mcp.pid

​
Options

​
--http
boolean
default:"false"
Use HTTP transport instead of stdio
​
--daemon
boolean
default:"false"
Run as background daemon (requires --http)
​
--port
number
default:"8181"
HTTP port (requires --http)

​
MCP Tools Provided

The server exposes these tools to AI agents: Hybrid search with BM25 + vector + reranking. Parameters:
  • query (string, required) — Search query
  • collection (string) — Filter by collection
  • limit (number, default: 10) — Max results
  • minScore (number, default: 0) — Min score threshold
Vector semantic search only. Parameters:
  • query (string, required) — Search query
  • collection (string) — Filter by collection
  • limit (number, default: 10) — Max results
  • minScore (number, default: 0.3) — Min similarity threshold

​
list_collections

List all indexed collections. Parameters: None

​
get_document

Retrieve single document by path or docid. Parameters:
  • path (string, required) — Virtual path, filesystem path, or docid

​
multi_get

Batch retrieve multiple documents. Parameters:
  • pattern (string, required) — Glob pattern or comma-separated list
  • maxBytes (number, default: 10240) — Skip files larger than this

​
list_files

List files in a collection. Parameters:
  • collection (string) — Collection name (omit to list collections)
  • path (string) — Path prefix to filter by

​
Configuration

​
Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows): 
{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}
Restart Claude Desktop.

​
Cline (VS Code)

Add to MCP servers configuration: 
{
  "qmd": {
    "command": "qmd",
    "args": ["mcp"]
  }
}

​
Custom HTTP Client

# Start server
qmd mcp --http --port 8181

# Connect to http://localhost:8181/mcp
# Use SSE for events, POST for requests

​
Daemon Management

# Start daemon
qmd mcp --http --daemon

# Check if running
qmd status  # Shows "MCP: running (PID 12345)"

# View logs
tail -f ~/.cache/qmd/mcp.log

# Stop daemon
qmd mcp stop
Daemon:
  • Auto-restarts if parent process dies (detached)
  • Writes logs to ~/.cache/qmd/mcp.log (truncated on each start)
  • Stores PID in ~/.cache/qmd/mcp.pid
  • Cleaned up automatically if process dies

​
Error Handling

Port already in use: 
Port 8181 already in use. Try a different port with --port.
Use --port to specify different port. Daemon already running: 
Already running (PID 12345). Run 'qmd mcp stop' first.
Stop existing daemon before starting new one. Stale PID file: Auto-cleaned silently if process not running.

​
Examples

# Standard stdio for Claude Desktop
qmd mcp

# HTTP for web clients
qmd mcp --http

# Background daemon on custom port
qmd mcp --http --daemon --port 9000

# Stop daemon
qmd mcp stop

# Check daemon status
qmd status

​
Security Notes

  • Stdio: Secure (direct process communication)
  • HTTP: No authentication — bind to localhost only
  • Daemon: Accessible to all local processes on the port
For remote access, use SSH tunneling: 
ssh -L 8181:localhost:8181 remote-host

qmd status

Check if MCP daemon is running

MCP integration guide

Set up MCP with AI agents

qmd query

Test search before exposing via MCP