Html2md MCP

🚀 HTML to Markdown MCP Server

An MCP (Model Context Protocol) server designed to convert HTML webpages into a clean Markdown format. It can reduce the HTML size by approximately 90 - 95% while preserving tables, images, and important content, making it ideal for AI context.

🚀 Quick Start

After configuration, the MCP server will be accessible in Claude Desktop. You can utilize the html_to_markdown tool. For instance:

Convert this webpage to markdown: https://example.com/article

✨ Features

• Converts HTML from URLs to clean Markdown.
• Preserves tables, images, and links.
• Removes unnecessary elements such as scripts, styles, navigation, footers, and headers.
• Achieves significant size reduction, typically compressing by 90 - 95%.
• Offers configurable options for images, tables, and links.
• Built with trafilatura and BeautifulSoup4 for robust extraction.
• Stream processing for efficient handling of large pages.
• Size limits to prevent downloading excessively large content (1MB - 50MB).
• Optional caching to speed up repeated conversions of the same URLs.
• 🌐 Browser mode with Playwright - Handles JavaScript - heavy sites and authenticated pages:
  • Execute JavaScript (perfect for SPAs: React, Vue, Angular).
  • Use your browser profile with cookies (access authenticated pages!).
  • Support for Chrome, Firefox, WebKit.
  • Configurable wait strategies for dynamic content.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• uv package manager (recommended) or pip.

Install with uv (recommended)

# Clone the repository
git clone <your-repo-url>
cd html2md

# Install dependencies
uv pip install -e .

# Install Playwright browsers (required for browser mode)
playwright install chromium

Install with pip

# Clone the repository
git clone <your-repo-url>
cd html2md

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Install Playwright browsers (required for browser mode)
playwright install chromium

Docker Installation (Recommended for Production)

The easiest way to use html2md is with Docker:

# Build the image
docker build -t html2md .

# Or use pre - built image (when published)
docker pull your-registry/html2md:latest

For Claude Desktop, configure with Docker:

{
  "mcpServers": {
    "html2md": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "html2md"
      ]
    }
  }
}

Docker Image Features:

• Pre - installed Playwright with Chromium.
• Optimized for minimal size (~1GB).
• Non - root user for security.
• Ready to use - no additional setup required.

💻 Usage Examples

Basic Usage

Convert this webpage to markdown: https://example.com/article

Advanced Usage

Example 2: With options

Use the html_to_markdown tool with:
- url: https://example.com/docs
- include_images: false
- include_tables: true

Example 3: Browser mode for JavaScript - heavy sites

Use the html_to_markdown tool with:
- url: https://spa-application.com
- fetch_method: playwright
- wait_for: networkidle

Example 4: Access authenticated pages

Use the html_to_markdown tool with:
- url: https://private-site.com/dashboard
- fetch_method: playwright
- use_user_profile: true
- browser_type: chromium

Note: For use_user_profile=true, make sure Chrome is closed before running.

Tool Parameters

📚 Documentation

Configuration

Add the server to your Claude Desktop configuration file:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "html2md": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/html2md",
        "run",
        "html2md"
      ]
    }
  }
}

Windows

Edit %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "html2md": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\html2md",
        "run",
        "html2md"
      ]
    }
  }
}

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "html2md": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/html2md",
        "run",
        "html2md"
      ]
    }
  }
}

🔧 Technical Details

Architecture

The project consists of three main modules:

converter.py

Core HTML to Markdown conversion functionality:

• fetch_html(): Downloads HTML from URL.
• clean_html(): Removes unnecessary elements with BeautifulSoup.
• convert_to_markdown(): Converts cleaned HTML to Markdown with trafilatura.
• html_to_markdown(): Main workflow combining all steps.

server.py

MCP server implementation:

• Registers the html_to_markdown tool.
• Handles tool calls and error responses.
• Runs async MCP server with stdio transport.

utils.py

Utility functions:

• Hash calculation for caching.
• Text formatting and truncation.
• Domain extraction.
• Filename sanitization.

cache.py

In - memory caching system:

• SimpleCache class with TTL support.
• Global cache instance management.
• Automatic expiration of old entries.
• Hash - based cache keys for URL + parameters.

browser.py

Playwright browser automation:

• fetch_html_playwright() - Async browser - based HTML fetching.
• Support for Chromium, Firefox, WebKit.
• User profile integration for authenticated access.
• Configurable wait strategies for dynamic content.

Development

Install development dependencies

uv pip install -e ".[dev]"

Run tests

pytest

Code formatting

# Format with black
black src/ tests/

# Lint with ruff
ruff check src/ tests/

Type checking

mypy src/

Performance

Typical conversion results:

• Original HTML: ~500KB - 2MB.
• Markdown output: ~25KB - 100KB.
• Compression: 90 - 95%.
• Processing time: 2 - 10 seconds (depending on page size and network).

📄 License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Credits

Built with:

• MCP SDK - Model Context Protocol.
• trafilatura - Web content extraction.
• BeautifulSoup4 - HTML parsing.