Html2md MCP

HTML到Markdown MCP服务器

MCP（模型上下文协议）服务器，用于将HTML网页转换为干净的Markdown格式。将HTML大小减少约90-95%，同时保留表格、图像和重要内容，非常适合人工智能环境。

特性

• 将HTML从URL转换为干净的Markdown
• 保留表、图像和链接
• 删除不必要的元素（脚本、样式、导航、页脚、页眉）
• 显著减小尺寸（通常压缩90-95%）
• 图像、表格和链接的可配置选项
• 内置 trafilatura 和 BeautifulSoup4 用于稳健提取
• 流处理 用于高效处理大页面
• 大小限制 防止下载过大的内容（1MB-50MB）
• 可选缓存 加快相同网址的重复转换
• 🌐 Playwright浏览器模式 -处理JavaScript繁重的网站和经过身份验证的页面

- 执行JavaScript（非常适合SPA：React、Vue、Angular） - 使用带有Cookie的浏览器配置文件（访问经过身份验证的页面！） - 支持Chrome、Firefox、WebKit - 动态内容的可配置等待策略

安装

先决条件

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

使用紫外线进行安装（推荐）

# Clone the repository
git clone 
cd html2md

# Install dependencies
uv pip install -e .

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

使用pip安装

# Clone the repository
git clone 
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镜像功能：

• 预装Chromium的Playwright
• 针对最小大小（~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"
      ]
    }
  }
}

视窗

编辑 %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方法-“fetch（快速）”或“descriptor（处理JS、auth）”
• browser_type （可选，默认：“chromium”）：要使用的浏览器-“chromum”、“firefox”或“webkit”
• headless （可选，默认值：true）：在无头模式下运行浏览器
• wait_for （可选，默认值：“networkidle”）：等待策略-“load”、“domcontentloaded”或“networkidlet”
• 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

内存缓存系统：

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

browser.py

Playwright浏览器自动化：

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

故障排除

服务器未出现在Claude Desktop中

1. 检查路径是否正确 claude_desktop_config.json 绝对正确
2. 完全重新启动克劳德桌面
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
• 浏览器启动失败：检查您是否有足够的权限和磁盘空间
• 用户配置文件错误：使用前请确保Chrome已完全关闭 use_user_profile: true
• 页面未完全加载：尝试不同 wait_for 策略：

- "load" -最快，等待页面加载事件 - "domcontentloaded" -等待DOM准备就绪 - "networkidle" -最慢但最可靠，等待网络空闲

• 身份验证不起作用：确保您正在使用 browser_type: chromium 和 use_user_profile: true

演出

典型转换结果：

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

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题或拉取请求。

鸣谢

内置：

• MCP-SDK -模型上下文协议
• 交通 -Web内容提取
• 美丽的Soup4 -HTML解析