How QMD's MCP Server Enables Claude Desktop and AI Agents to Interact with QMD

QMD's MCP server acts as a protocol bridge that exposes the QMD CLI through stdio for Claude Desktop integration or HTTP for remote AI agents, enabling real-time document search and query operations via structured JSON messages.

QMD (Query Markup Documents) is an open-source document search and retrieval system. The tobi/qmd repository includes a dedicated MCP (Multi-Client Protocol) server that transforms QMD from a command-line tool into a programmable service, allowing Claude Desktop and custom AI agents to execute searches programmatically without spawning separate subprocesses for each command.

What Is QMD's MCP Server?

The MCP server is a thin transport layer implemented in src/mcp.ts that wraps the core QMD CLI logic from src/qmd.ts. It normalizes all operations into a JSON-RPC-like protocol, ensuring that external clients receive consistent response envelopes regardless of the underlying transport mechanism.

The server operates in two distinct modes to accommodate different integration scenarios: stdio for embedded desktop applications and HTTP for networked AI agents.

Transport Modes for Claude Desktop and AI Agents

stdio Mode for Claude Desktop Integration

In stdio mode, the MCP server reads newline-terminated JSON messages from stdin and writes responses to stdout. This mode is designed specifically for Claude Desktop, which spawns the process internally and communicates via standard streams.

# Claude Desktop launches this internally

qmd mcp --stdio

The desktop UI sends JSON payloads such as {"command":"search","args":["vector","machine learning"]} and receives immediate results without the overhead of process spawning.

HTTP Mode for Remote AI Agents

HTTP mode exposes QMD as a REST-like API, listening on a configurable TCP port (default 8181). This enables independent AI agents, automation scripts, or multi-user systems to interact with QMD over the network.

# Run as a background service

qmd mcp --http --port 8181

The HTTP server exposes a single endpoint at POST /command that accepts JSON bodies and returns normalized responses.

Integrating AI Agents with QMD's HTTP MCP Server

Node.js Agent Example

AI agents written in Node.js can interact with QMD using standard fetch requests. The following example demonstrates how to wrap the HTTP API in a reusable client function:

import fetch from "node-fetch";

async function qmdCommand(cmd, args = []) {
  const resp = await fetch("http://localhost:8181/command", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ command: cmd, args })
  });
  const data = await resp.json();
  if (!data.ok) throw new Error(data.error);
  return data.result;
}

// Example: search the index
(async () => {
  const result = await qmdCommand("search", ["vector", "machine learning"]);
  console.log(result);
})();

This pattern enables retrieval-augmented generation (RAG) workflows where AI agents automatically query QMD indices, re-rank results, or update document collections based on conversational context.

Core Architecture and Security Model

The MCP server in src/mcp.ts implements a strict dispatch and normalization layer that preserves QMD's security guarantees.

Command Dispatch Flow

1. Request Parsing: The server validates incoming JSON against expected schemas for commands like search, query, or status.
2. CLI Invocation: Validated commands are forwarded to the core implementation in src/qmd.ts, ensuring all business logic remains centralized.
3. Result Wrapping: Raw CLI output is encapsulated in a structured envelope: {"ok": true, "result": "...", "error": null}.

Security and Isolation

The MCP server does not expose file-system paths directly. All operations route through the validated QMD CLI, maintaining the same safety guarantees as manual CLI invocation. This prevents path traversal attacks and ensures that AI agents can only perform operations explicitly supported by the QMD command set.

Summary

• QMD's MCP server bridges the QMD CLI with external clients through stdio and HTTP transports, enabling seamless integration with Claude Desktop and custom AI agents.
• stdio mode (qmd mcp --stdio) supports embedded desktop applications that communicate via standard input/output streams.
• HTTP mode (qmd mcp --http --port 8181) exposes a JSON API at POST /command for networked AI agents and automation scripts.
• The architecture in src/mcp.ts normalizes all responses into structured JSON envelopes while routing commands through src/qmd.ts to preserve security and validation logic.

Frequently Asked Questions

What transport protocols does QMD's MCP server support?

QMD's MCP server supports two transport protocols: stdio for local process communication and HTTP for networked access. The stdio mode reads JSON commands from stdin and writes responses to stdout, making it ideal for Claude Desktop integration. HTTP mode listens on a TCP port (default 8181) and accepts POST requests to the /command endpoint, enabling remote AI agents to interact with QMD over the network.

How do I configure Claude Desktop to use QMD's MCP server?

Claude Desktop automatically spawns the MCP server using the command qmd mcp --stdio. You do not need to manually start the server; instead, ensure the qmd binary is available in your system PATH. Claude Desktop will handle the lifecycle of the process, sending search and query commands via standard input and rendering the JSON responses in the chat interface. For detailed setup instructions, refer to the documentation in skills/qmd/references/mcp-setup.md.

Can I run QMD's MCP server as a background service?

Yes, the HTTP mode is designed for running as a persistent background service. Start the server with qmd mcp --http --port 8181 (or specify a custom port) and optionally daemonize the process using your operating system's service manager (such as systemd on Linux or launchd on macOS). This configuration allows multiple AI agents or client applications to share a single QMD instance without the overhead of spawning new processes for each request.

Is the MCP server API compatible with other AI agents besides Claude?

Yes, the HTTP transport exposes a language-agnostic JSON API that any AI agent or automation script can consume. While the stdio mode is optimized for Claude Desktop's specific integration pattern, the HTTP mode accepts standard POST requests with JSON bodies containing command and args fields. This makes it compatible with Python-based agents, Node.js applications, curl scripts, or any HTTP client capable of sending JSON payloads to localhost:8181/command.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}