Markdown Query
A jq-like Markdown query language for command-line processing
What is Markdown Query?
Markdown Query is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to jq-like markdown query language for command-line processing
A jq-like Markdown query language for command-line processing
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A jq-like Markdown query language for command-line processin
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mqConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Markdown Query
mq is a jq-inspired query and transformation language for Markdown, implemented in Rust and exposing an MCP server interface so AI assistants can query, filter, and transform Markdown documents programmatically. It understands Markdown structure natively — headings, code blocks, links, tables, and list items — so you can write concise queries like '.h(1..3)' to extract headings or '.code("rust")' to pull out Rust code blocks without writing fragile regex. Technical writers, developers, and documentation teams use mq to bulk-process Markdown files, extract data from documentation corpora, and automate content pipelines from within their AI workflow.
Prerequisites
- Rust toolchain (if building from source via cargo install mq-run), OR Homebrew on macOS ('brew install mq'), OR a pre-built binary from GitHub Releases
- The mq binary available on your PATH before starting the MCP server
- An MCP-compatible client such as Claude Desktop or Claude Code
Install the mq binary
Install mq using your preferred method. The quickest cross-platform option is the install script; macOS users can use Homebrew. Cargo is available if you already have a Rust toolchain.
# Quick install script
curl -sSL https://mqlang.org/install.sh | bash
# macOS Homebrew
brew install mq
# Cargo
cargo install mq-runVerify the installation
Confirm mq is on your PATH and working before configuring the MCP server.
mq --version
echo '# Hello\n\nWorld' | mq '.h'Configure the MCP server in Claude Desktop
Add mq to your claude_desktop_config.json. The server binary is invoked with the 'mcp' subcommand to start it in MCP server mode.
{
"mcpServers": {
"mq": {
"command": "mq",
"args": ["mcp"]
}
}
}Understand the query language basics
mq expressions are piped filters. .h extracts all headings, .h(1) extracts only H1 headings, .code("python") extracts Python code blocks, and .link.url extracts all link URLs. Combine filters with pipes: .h | .text to get heading text only.
# Extract all headings from a file
mq '.h' README.md
# Extract only H2 and H3 headings
mq '.h(2..3)' README.md
# Pull out all Python code blocks
mq '.code("python")' docs.md
# Get all link URLs
mq '.link.url' README.mdUse the REPL for interactive exploration
mq ships with a REPL for testing queries interactively before automating them. Start it with 'mq repl' and pass a Markdown file to query against.
mq repl README.mdMarkdown Query Examples
Client configuration
Claude Desktop configuration to run the mq MCP server using the installed mq binary.
{
"mcpServers": {
"mq": {
"command": "mq",
"args": ["mcp"]
}
}
}Prompts to try
Example prompts for querying and transforming Markdown content through the MCP server.
- "Use mq to extract all H2 headings from README.md"
- "Find every code block tagged as 'bash' in the docs/ directory"
- "Extract all hyperlink URLs from CHANGELOG.md and list them"
- "Use mq to filter docs/api.md for sections that contain the word 'authentication'"
- "Aggregate all Markdown files in the project and extract their H1 titles as a list"Troubleshooting Markdown Query
MCP server fails to start with 'command not found: mq'
The mq binary must be on the PATH used by your MCP client process. If you installed via Homebrew, run 'brew info mq' to find the binary location and use its absolute path in the 'command' field of the config (e.g. /opt/homebrew/bin/mq).
Query returns empty results on a valid Markdown file
Check that the file uses standard Markdown syntax. mq parses ATX-style headings (## heading), not Setext-style underlined headings. Run 'mq ".h" file.md' directly in the terminal to debug the query outside the MCP server.
Complex queries with pipes do not produce expected output
Test each filter stage independently in the REPL ('mq repl file.md') to isolate which part of the pipeline is failing. The -O flag (optimization) can sometimes reorder expressions; disable it with '-O none' when debugging.
Frequently Asked Questions about Markdown Query
What is Markdown Query?
Markdown Query is a Model Context Protocol (MCP) server that jq-like markdown query language for command-line processing It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Markdown Query?
Follow the installation instructions on the Markdown Query GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Markdown Query?
Markdown Query works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Markdown Query free to use?
Yes, Markdown Query is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Markdown Query Alternatives — Similar Developer Tools Servers
Looking for alternatives to Markdown Query? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Markdown Query in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Markdown Query?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.