Supports GitHub Flavored Markdown conventions for linting and validating Markdown files created for GitHub repositories.
Offers cross-platform support for Markdown linting and fixing on Linux systems.
Provides cross-platform support for Markdown linting and fixing on macOS systems.
Provides tools for linting, validating, and auto-fixing Markdown files to ensure compliance with established standards including CommonMark and GitHub Flavored Markdown conventions.
markdownlint-mcp
A Model Context Protocol (MCP) server for markdown linting, formatting, and compliance checking.
Overview
This MCP server provides AI assistants with the ability to lint, validate, and auto-fix Markdown files to ensure compliance with established Markdown standards and best practices.
The Problem
While many MCP servers exist for converting various file formats to Markdown, there was no MCP server specifically designed for linting and ensuring compliance of existing Markdown files. This creates a gap in the workflow where Markdown content may be created or converted but not validated for quality and consistency.
Solution
markdownlint-mcp
bridges this gap by providing:
- Markdown linting using industry-standard rules
- Automatic fixing of common Markdown issues
- Compliance validation against established standards
- Seamless integration with MCP-compatible AI assistants
Features
MCP Tools Provided
lint_markdown
- Analyze a Markdown file and return detailed issuesfix_markdown
- Automatically fix Markdown issues and return corrected contentget_configuration
- Display current linting rules and configuration
Standards-Based Approach
- Uses markdownlint default ruleset (community standard)
- Based on CommonMark specification
- Follows GitHub Flavored Markdown conventions
- Supports all 52 official markdownlint rules
Auto-Fixable Rules
Our MCP server can automatically fix 30 out of 52 official markdownlint rules (58%). These rules are deterministic and can be fixed without human judgment:
Whitespace & Formatting (9 rules)
- MD009 - Trailing spaces
- MD010 - Hard tabs
- MD012 - Multiple consecutive blank lines
- MD022 - Headings surrounded by blank lines
- MD031 - Fenced code blocks surrounded by blank lines
- MD032 - Lists surrounded by blank lines
- MD047 - Files should end with single newline
- MD058 - Tables surrounded by blank lines
- MD027 - Multiple spaces after blockquote symbol
Heading Formatting (6 rules)
- MD018 - No space after hash
- MD019 - Multiple spaces after hash
- MD020 - No space inside closed ATX
- MD021 - Multiple spaces inside closed ATX
- MD023 - Headings start at line beginning
- MD026 - Trailing punctuation in heading
List Formatting (4 rules)
- MD004 - Unordered list style
- MD005 - List item indentation consistency
- MD007 - Unordered list indentation
- MD030 - Spaces after list markers
Link & Text Formatting (7 rules)
- MD011 - Reversed link syntax
- MD034 - Bare URL used
- MD037 - Spaces inside emphasis
- MD038 - Spaces inside code spans
- MD039 - Spaces inside link text
- MD049 - Emphasis style
- MD050 - Strong style
Advanced Fixable (4 rules)
- MD014 - Dollar signs before commands
- MD044 - Proper names capitalization
- MD051 - Link fragments validation
- MD053 - Unused reference definitions
Detection-Only Rules
The following 22 rules (42%) cannot be automatically fixed because they require human judgment, content understanding, or style decisions:
Structural/Content Rules (12 rules)
- MD001 - Heading increment (requires understanding document structure)
- MD003 - Heading style consistency (needs style preference decision)
- MD013 - Line length (requires content-aware line breaking)
- MD024 - Duplicate headings (could break document structure/navigation)
- MD025 - Multiple H1s (requires understanding document hierarchy)
- MD028 - Blank line in blockquote (ambiguous semantic intent)
- MD029 - Ordered list numbering (style preference)
- MD035 - Horizontal rule style (style preference)
- MD036 - Emphasis as heading (requires semantic understanding)
- MD041 - First line H1 (may break existing document structure)
- MD043 - Required heading structure (document-specific requirements)
- MD046 - Code block style (style preference)
Content/Language Rules (5 rules)
- MD033 - Inline HTML (may be intentional/necessary)
- MD040 - Code language specification (requires code language knowledge)
- MD045 - Alt text for images (requires understanding image content)
- MD059 - Descriptive link text (requires understanding context/purpose)
- MD042 - Empty links (may be placeholders or templates)
Reference/Link Rules (3 rules)
- MD052 - Reference links defined (may be external or conditional)
- MD054 - Link/image style (style preference)
- MD056 - Table column count (may be intentional formatting)
Table Rules (2 rules)
- MD055 - Table pipe style (style preference)
- MD048 - Code fence style (style preference)
Installation
Usage
With Claude Desktop
Add to your Claude Desktop MCP configuration:
With Other MCP Clients
This server works with any MCP-compatible client including:
- Claude Desktop
- Cursor
- Cline
- VS Code with MCP support
Example Workflows
Lint a Markdown File
Fix Markdown Issues
Validate Compliance
Technical Approach
- Direct library integration with
markdownlint
npm package - No external CLI dependencies required
- Cross-platform support (Windows, macOS, Linux)
- Single installation - no additional tools needed
- Efficient processing via direct API calls
Development Status
🚧 In Development - This project is currently being built with the goal of:
- Initial release with core functionality
- Community testing and feedback
- Submission to official MCP collection for maximum visibility
- Continuous improvement based on user needs
Contributing
We welcome contributions! This project aims to become part of the official MCP server collection and follows MCP best practices.
Roadmap
- Core MCP server implementation
- Comprehensive testing suite
- Documentation and examples
- Community feedback integration
- Submission to official MCP collection
License
MIT License - see LICENSE file for details
Related Projects
- markdownlint - The underlying linting engine
- Model Context Protocol - The protocol this server implements
- MCP Servers Collection - Official MCP servers
Support
For issues, questions, or contributions, please use the GitHub issues page.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Provides AI assistants with the ability to lint, validate, and auto-fix Markdown files to ensure compliance with established Markdown standards and best practices.
Related MCP Servers
- AsecurityAlicenseAqualityConverts various file types and web content to Markdown format. It provides a set of tools to transform PDFs, images, audio files, web pages, and more into easily readable and shareable Markdown text.Last updated -1021,611TypeScriptMIT License
- AsecurityAlicenseAqualityConverts various file formats to Markdown using the MarkItDown utility and can be integrated with MCP clients for seamless document processing and conversion.Last updated -26PythonMIT License
- AsecurityAlicenseAqualityA Model Context Protocol implementation that enables AI assistants to interact with markdown documentation files, providing capabilities for document management, metadata handling, search, and documentation health analysis.Last updated -1434611TypeScriptMIT License
- AsecurityFlicenseAqualityA server that converts various file formats (PDF, images, Office documents, etc.) to Markdown descriptions using Cloudflare AI services.Last updated -1233JavaScript