Html2md MCP

🚀 HTML 转 Markdown MCP 服务器

这是一个用于将 HTML 网页转换为简洁 Markdown 格式的 MCP（模型上下文协议）服务器。它能在保留表格、图像和重要内容的同时，将 HTML 文件大小缩减约 90 - 95%，非常适合用于 AI 上下文。

✨ 主要特性

• 可将 URL 中的 HTML 转换为简洁的 Markdown 格式。
• 保留表格、图像和链接。
• 移除不必要的元素（脚本、样式、导航栏、页脚、页眉）。
• 显著减小文件大小（通常压缩率为 90 - 95%）。
• 可对图像、表格和链接进行配置。
• 基于 trafilatura 和 BeautifulSoup4 构建，提取功能强大。
• 流式处理，可高效处理大页面。
• 大小限制，防止下载过大的内容（1MB - 50MB）。
• 可选缓存，加快对相同 URL 的重复转换速度。
• 🌐 支持使用 Playwright 的浏览器模式：可处理 JavaScript 密集型网站和需要身份验证的页面。
  • 执行 JavaScript（非常适合单页应用：React、Vue、Angular）。
  • 使用带有 cookie 的浏览器配置文件（可访问需要身份验证的页面）。
  • 支持 Chrome、Firefox、WebKit。
  • 可对动态内容配置等待策略。

📦 安装指南

前提条件

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

使用 uv 安装（推荐）

# 克隆仓库
git clone <your-repo-url>
cd html2md

# 安装依赖
uv pip install -e .

# 安装 Playwright 浏览器（浏览器模式需要）
playwright install chromium

使用 pip 安装

# 克隆仓库
git clone <your-repo-url>
cd html2md

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安装依赖
pip install -e .

# 安装 Playwright 浏览器（浏览器模式需要）
playwright install chromium

Docker 安装（生产环境推荐）

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

# 构建镜像
docker build -t html2md .

# 或者使用预构建的镜像（发布后）
docker pull your-registry/html2md:latest

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

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

Docker 镜像特性：

• 预安装了带有 Chromium 的 Playwright。
• 经过优化，体积最小化（约 1GB）。
• 使用非 root 用户，提高安全性。
• 可直接使用，无需额外设置。

💻 使用示例

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

基础用法

将此网页转换为 Markdown：https://example.com/article

带选项的用法

使用 html_to_markdown 工具，参数如下：
- url: https://example.com/docs
- include_images: false
- include_tables: true

用于 JavaScript 密集型网站的浏览器模式

使用 html_to_markdown 工具，参数如下：
- url: https://spa-application.com
- fetch_method: playwright
- wait_for: networkidle

访问需要身份验证的页面

使用 html_to_markdown 工具，参数如下：
- 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"（处理 JavaScript 和身份验证）。
• 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

代码格式化

# 使用 black 进行格式化
black src/ tests/

# 使用 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 工具。
• 处理工具调用和错误响应。
• 使用标准输入输出传输运行异步 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 日志以查看错误信息。

安装问题

# 验证 Python 版本
python --version  # 应为 3.10 或更高版本

# 尝试重新安装依赖
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 - 模型上下文协议
• trafilatura - 网页内容提取
• BeautifulSoup4 - HTML 解析