HTML to Markdown MCP Server

HTML 转 Markdown MCP 服务

用于将 HTML 网页转换为整洁 Markdown 格式的 MCP（Model Context Protocol）服务。在保留表格、图片和重要内容的同时，可将 HTML 体积缩小约 90-95%，非常适合用作 AI 上下文。

功能

• 将 URL 中的 HTML 转换为整洁的 Markdown
• 保留表格、图片和链接
• 移除不必要的元素（脚本、样式、导航、页脚、页眉）
• 显著缩小体积（通常压缩 90-95%）
• 提供图片、表格和链接的可配置选项
• 使用 trafilatura 和 BeautifulSoup4 构建，确保稳健提取
• 流式处理，高效处理大型页面
• 大小限制，避免下载过大的内容（1MB-50MB）
• 可选缓存，加快对相同 URL 的重复转换
• 🌐 使用 Playwright 的浏览器模式——支持 JavaScript 密集型网站和需身份验证的页面
  • 执行 JavaScript（非常适合 SPA：React、Vue、Angular）
  • 使用浏览器配置文件中的 Cookie（访问需身份验证的页面！）
  • 支持 Chrome、Firefox、WebKit
  • 提供动态内容的可配置等待策略

安装

前提条件

• Python 3.10 或更高版本
• uv 包管理器（推荐）或 pip

使用 uv 安装（推荐）

# 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

使用 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 安装（生产环境推荐）

使用 html2md 最简单的方式是通过 Docker：

# Build the image
docker build -t html2md .

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

对于 Claude Desktop，使用 Docker 进行配置：

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

Docker 镜像功能：

• 预装 Playwright 和 Chromium
• 针对最小体积进行优化（约 1GB）
• 使用非 root 用户，提升安全性
• 开箱即用，无需额外设置

配置

将服务添加到 Claude Desktop 配置文件：

macOS

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

Windows

编辑 %APPDATA%/Claude/claude_desktop_config.json：

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

Linux

编辑 ~/.config/Claude/claude_desktop_config.json：

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

使用

配置完成后，MCP 服务将在 Claude Desktop 中可用。你可以使用 html_to_markdown 工具：

示例 1：基本转换

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

示例 2：使用选项

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

示例 3：用于 JavaScript 密集型网站的浏览器模式

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

示例 4：访问需身份验证的页面

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

注意： 使用 use_user_profile=true 时，请确保运行前已关闭 Chrome。

工具参数

基本参数：

• url（必填）：要转换的网页 URL
• include_images（可选，默认值：true）：在 Markdown 中包含图片
• include_tables（可选，默认值：true）：在 Markdown 中包含表格
• include_links（可选，默认值：true）：在 Markdown 中包含链接
• timeout（可选，默认值：30）：请求超时时间，单位为秒（5-120）

性能参数：

• max_size（可选，默认值：10MB）：可下载内容的最大大小，单位为字节（1MB-50MB）
• use_cache（可选，默认值：false）：启用缓存，加快重复转换
• cache_ttl（可选，默认值：3600）：缓存生存时间，单位为秒（60-86400）

浏览器模式参数：

• fetch_method（可选，默认值："fetch"）：获取方式——"fetch"（快速）或 "playwright"（支持 JS 和身份验证）
• browser_type（可选，默认值："chromium"）：要使用的浏览器——"chromium"、"firefox" 或 "webkit"
• headless（可选，默认值：true）：以无头模式运行浏览器
• wait_for（可选，默认值："networkidle"）：等待策略——"load"、"domcontentloaded" 或 "networkidle"
• use_user_profile（可选，默认值：false）：使用浏览器配置文件中的 Cookie（需要关闭 Chrome）

开发

安装开发依赖项

uv pip install -e ".[dev]"

运行测试

pytest

代码格式化

# Format with black
black src/ tests/

# Lint with ruff
ruff check src/ tests/

类型检查

mypy src/

架构

该项目由三个主要模块组成：

converter.py

HTML 转 Markdown 的核心功能：

• fetch_html()：从 URL 下载 HTML
• clean_html()：使用 BeautifulSoup 移除不必要的元素
• convert_to_markdown()：使用 trafilatura 将清理后的 HTML 转换为 Markdown
• html_to_markdown()：组合所有步骤的主工作流

server.py

MCP 服务实现：

• 注册 html_to_markdown 工具
• 处理工具调用和错误响应
• 使用 stdio 传输运行异步 MCP 服务

utils.py

实用函数：

• 用于缓存的哈希计算
• 文本格式化和截断
• 提取域名
• 清理文件名

cache.py

内存缓存系统：

• 支持 TTL 的 SimpleCache 类
• 全局缓存实例管理
• 自动过期旧条目
• 基于 URL 和参数生成哈希缓存键

browser.py

Playwright 浏览器自动化：

• fetch_html_playwright() - 基于异步浏览器的 HTML 获取
• 支持 Chromium、Firefox、WebKit
• 集成用户配置文件以进行身份验证访问
• 为动态内容提供可配置的等待策略

故障排除

Claude Desktop 中未显示服务

1. 检查 claude_desktop_config.json 中的路径是否为绝对路径且正确
2. 完全重启 Claude Desktop
3. 检查 Claude Desktop 日志中的错误

安装问题

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

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

转换错误

• 超时错误：增大 timeout 参数
• 内容为空：某些网站可能会阻止自动请求，或使用 JavaScript 渲染
  • 解决方案：使用 fetch_method: playwright 执行 JavaScript
• 解析错误：网页结构可能比较特殊或格式不正确
• 内容过大：增大 max_size 参数（最高可达 50MB），否则页面可能超出限制
• 缓存问题：如需获取最新内容，可使用 use_cache: false 禁用缓存

浏览器模式问题

• 未安装 Playwright：运行 playwright install chromium
• 浏览器启动失败：检查是否有足够的权限和磁盘空间
• 用户配置文件错误：使用 use_user_profile: true 前，确保 Chrome 已完全关闭
• 页面未完全加载：尝试不同的 wait_for 策略：
  • "load" - 速度最快，等待页面加载事件
  • "domcontentloaded" - 等待 DOM 就绪
  • "networkidle" - 速度最慢但最可靠，等待网络空闲
• 身份验证无效：确保使用 browser_type: chromium 和 use_user_profile: true

性能

典型的转换结果：

• 原始 HTML：约 500KB - 2MB
• Markdown 输出：约 25KB - 100KB
• 压缩率：90-95%
• 处理时间：2-10 秒（取决于页面大小和网络状况）

许可证

MIT

贡献

欢迎贡献！欢迎提交问题或拉取请求。

致谢

使用以下项目构建：

• MCP SDK - Model Context Protocol
• trafilatura - 网页内容提取
• BeautifulSoup4 - HTML 解析