HTML to Markdown MCP Server

MCP (Model Context Protocol) server for converting HTML webpages to clean Markdown format. Reduces HTML size by ~90-95% while preserving tables, images, and important content - perfect for AI context.

Features

• Converts HTML from URLs to clean Markdown

• Preserves tables, images, and links

• Removes unnecessary elements (scripts, styles, navigation, footers, headers)

• Significant size reduction (typically 90-95% compression)

• 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

Related MCP server: lilFetch

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

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"
      ]
    }
  }
}

Usage

Once configured, the MCP server will be available in Claude Desktop. You can use the html_to_markdown tool:

Example 1: Basic conversion

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

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

Basic Parameters:

• url (required): URL of the webpage to convert

• include_images (optional, default: true): Include images in Markdown

• include_tables (optional, default: true): Include tables in Markdown

• include_links (optional, default: true): Include links in Markdown

• timeout (optional, default: 30): Request timeout in seconds (5-120)

Performance Parameters:

• max_size (optional, default: 10MB): Maximum size of content to download in bytes (1MB-50MB)

• use_cache (optional, default: false): Enable caching for faster repeated conversions

• cache_ttl (optional, default: 3600): Cache time-to-live in seconds (60-86400)

Browser Mode Parameters:

• fetch_method (optional, default: "fetch"): Fetch method - "fetch" (fast) or "playwright" (handles JS, auth)

• browser_type (optional, default: "chromium"): Browser to use - "chromium", "firefox", or "webkit"

• headless (optional, default: true): Run browser in headless mode

• wait_for (optional, default: "networkidle"): Wait strategy - "load", "domcontentloaded", or "networkidle"

• use_user_profile (optional, default: false): Use your browser profile with cookies (requires Chrome closed)

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/

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

Troubleshooting

Server not appearing in Claude Desktop

1. Check that the path in claude_desktop_config.json is absolute and correct

2. Restart Claude Desktop completely

3. Check Claude Desktop logs for errors

Installation issues

# Verify Python version
python --version  # Should be 3.10+

# Try reinstalling dependencies
uv pip install --force-reinstall -e .

Conversion errors

• Timeout errors: Increase the timeout parameter

• Empty content: Some websites may block automated requests or use JavaScript rendering

  • Solution: Use fetch_method: playwright to execute JavaScript

• Parse errors: The webpage structure may be unusual or malformed

• Content too large: Increase the max_size parameter (up to 50MB) or the page exceeds limits

• Cache issues: Disable caching with use_cache: false if you need fresh content

Browser mode issues

• Playwright not installed: Run playwright install chromium

• Browser launch fails: Check that you have sufficient permissions and disk space

• User profile error: Make sure Chrome is completely closed before using use_user_profile: true

• Page doesn't load fully: Try different wait_for strategies:

  • "load" - fastest, waits for page load event

  • "domcontentloaded" - waits for DOM to be ready

  • "networkidle" - slowest but most reliable, waits for network to be idle

• Authentication not working: Ensure you're using browser_type: chromium and use_user_profile: true

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