AI导哈

文档转换服务

MCP-MarkItDown是一个使用Microsoft的MarkItDown包从互联网获取文档（PDF、DOCX、PPTX、XLSX等）并将其转换为Markdown格式的服务器。

  • by bradleyjlevine
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 bradleyjlevine/mcp-markitdown

使用说明

MCP标记

一种MCP服务器，使用微软的MarkItDown包从互联网上获取文档（PDF、DOCX、PPTX、XLSX等）并将其转换为markdown格式。

特性

  • 将各种文件类型转换为Markdown：

    • PDF文档
    • Word文档（docx）
    • PowerPoint演示文稿（pptx）
    • Excel电子表格（xlsx）
    • HTML页面
    • 增强可靠性的YouTube视频转录
    • 带有AI字幕的图像文件（Ollama可用时）

  • 保留文档结构，以便更好地处理LLM

  • 使用SABR保护旁路进行高级YouTube转录提取

  • 转录内容的自动重复数据删除

  • 对大型YouTube成绩单的分页支持

  • 强大的回退机制（youtube转录api→ yt-dlp）

  • 提供正确的错误处理和内容类型检测

  • 通过HTTP或stdio传输的模型上下文协议（MCP）公开功能

设置和安装

  1. 确保您安装了Python 3.11或更高版本
  2. 如果尚未安装uv包管理器，请安装： pip install uv
  3. 安装依赖项： uv pip install -e .

外部依赖项

在本地运行时（不使用Docker）：

  • 对于AI图像字幕，请安装Ollama： 下载Ollama

    • 安装Ollama后，运行以下命令之一以拉取受支持的模型：
      ollama pull gemma3:4b
# OR
ollama pull qwen2.5vl:7b

  • 对于增强的YouTube转录提取，可以选择运行bgutil-ytdlp锅提供程序容器：

    # Run the bgutil-provider container separately:
docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider

用法

作为MCP服务器运行

您可以通过以下方式之一运行MCP服务器：

选项1：使用Docker Compose（推荐）

# Start both the MCP server and bgutil-provider
docker-compose up -d

选项2：手动设置

  1. （可选）要增强YouTube转录提取，请运行bgutil提供程序容器：
docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider
  1. 运行MCP服务器：
# Default transport is now HTTP (port 8085)
uv run main.py

# For stdio transport
MCP_TRANSPORT=stdio uv run main.py
  1. 在本地运行时（不使用Docker Compose），设置bgutil提供程序URL，以便yt-dlp可以为YouTube使用SABR令牌：
# macOS/Linux
export YTDLP_BGUTIL_POT_PROVIDER_URL=http://127.0.0.1:4416

# Windows (PowerShell)
$env:YTDLP_BGUTIL_POT_PROVIDER_URL = "http://127.0.0.1:4416"

注意：应用程序现在可以在以下位置自动检测正在运行的提供程序 bgutil-provider:4416 （Docker）或 127.0.0.1:4416 （当地）。显式设置变量可确保行为一致。

  1. 使用 markitdown_fetch 带有指向要转换的文档的URL参数的工具

示例

请求：

markitdown_fetch(url="https://example.com/document.pdf")

答复：

{
  "markdown": "# Document Title\n\nDocument content converted to markdown..."
}

测试特定URL

您可以使用以下命令在不启动MCP服务器的情况下测试文档转换 --test 标志：

uv run main.py --test "https://example.com/document.pdf"

这将下载文档，将其转换为markdown，并显示转换结果的预览。

YouTube转录功能

该服务器包括增强的YouTube转录提取功能：

先进的提取方法

  1. 主要的，重要的 用于快速、高效提取的youtube转录api
  2. 退路： yt-dlp用于屏蔽视频的字幕解析
  3. 增强： bgutil-ytdlp锅提供商集成以绕过SABR保护

主要特点

  • 自动重复数据删除 删除重复的转录行
  • 元数据 包括视频标题、创建者、上传日期、持续时间、描述
  • 分页支持 处理大型成绩单 response_limit 参数
  • 多种格式 支持所有YouTube URL变体（YouTube.com、youtu.be、embed等）
  • 强大的回退 优雅地处理速率限制和访问限制

响应格式示例

{
  "markdown": "# Video Title\n\n**Creator:** Channel Name\n**Duration:** 15 minutes\n\n## Transcript\n\nTranscript content here...",
  "next_cursor": "1250",
  "has_more": true
}

支持的URL类型

  • PDF文档： https://example.com/document.pdf
  • Word文档： https://example.com/document.docx
  • PowerPoint演示文稿： https://example.com/presentation.pptx
  • Excel电子表格： https://example.com/spreadsheet.xlsx
  • HTML页面： https://example.com/page.html
  • YouTube视频： https://youtube.com/watch?v=... 或 https://youtu.be/...
  • 图像： https://example.com/image.jpg

运作原理

  1. 服务器接受指向文档的URL
  2. 对于YouTube网址：
    • 尝试使用youtube转录api提取转录
    • 如果API失败，则返回到带有字幕提取的yt-dlp
    • 使用bgutil-ytdlp提供程序绕过YouTube的SABR保护（如果可用）
    • 自动消除副本行
    • 包括视频元数据（标题、上传者、持续时间、描述）
    • 支持对大型成绩单进行分页
  3. 对于图像： 如果Ollama有支持的型号（gemma3:4b或qwen2.5vl:7b），它会生成一个描述性标题
  4. 其他文件： 下载到临时位置并使用Microsoft的markitdown包进行转换
  5. 文档转换为markdown格式，保留结构
  6. 临时文件已清理
  7. markdown内容作为响应返回

依赖项

Python包

  • markitdown[all]：微软用于文档转换的markitdown软件包
  • fastmcp：用于构建MCP服务器
  • 请求：用于从URL获取文档
  • beautifulsoup4：用于HTML解析和转录处理
  • yt-dlp[curl-cffi]：具有高级功能的增强型YouTube下载器
  • youtube转录api：主要的youtube转录提取库
  • 人性化：用于格式化视频持续时间和日期
  • ollama：用于与本地ollama实例交互以进行图像字幕
  • 枕头：用于图像处理和操作
  • pydub：用于音频处理（由一些markitdown组件使用）

可选增强功能

  • bgutil-ytdlp锅提供商：绕过YouTube的SABR保护，以提高可靠性

系统相关性

运行Docker容器时，会自动安装以下内容：

  • ffmpeg：用于音频/视频处理和格式转换
  • poppler-utils：用于PDF处理
  • libmagic1：用于文件类型检测

Docker支持

注： 默认传输模式现在是端口8085上的HTTP。这与Docker配合得很好，可以更容易地与其他服务集成。您仍然可以通过设置环境变量来使用stdio传输 MCP_TRANSPORT=stdio 运行应用程序时。

使用Docker构建和运行

该项目包括Docker支持，便于部署和与主机依赖关系隔离。

先决条件

  • Docker已安装在您的系统上
  • Ollama在主机上运行（不在容器中）

Docker Compose快速入门

现在有两个跑步选项（按 docker/):

  • 嵌入式提供程序（单容器）： docker/embedded

    • 生成文件： docker/embedded/Dockerfile
    • 作曲： docker/embedded/docker-compose.yml
    • 启动markitdown容器内的bgutil提供程序。

  • 最小拆分（两个容器）： docker/minimal

    • 生成文件： docker/minimal/Dockerfile
    • 作曲： docker/minimal/docker-compose.yml
    • 跑动 bgutil-provider 作为一项单独的服务；markitdown通过以下方式连接到它 YTDLP_BGUTIL_POT_PROVIDER_URL.
    • 默认为MCP stdio传输；集 MCP_TRANSPORT=streamable-http 以暴露HTTP。
  1. 克隆存储库并导航到项目目录
  2. 使用Docker Compose构建和运行：
# Option A: Embedded (single container; HTTP uses streamable-http)
cd docker/embedded
docker compose up --build

# Option B: Minimal split (markitdown + provider; defaults to stdio)
cd docker/minimal
docker compose up --build

# Linux note for both options:
# If host.docker.internal is unavailable, set OLLAMA_HOST to the bridge IP
# e.g. OLLAMA_HOST=http://172.17.0.1:11434 docker compose ...

Makefile快捷方式

为了方便起见，Makefile包含在常见任务中：

# Embedded (single container)
make up-embedded        # build + start
make logs-embedded      # tail logs
make down-embedded      # stop + remove
make test-embedded      # quick provider ping + sample test inside container

# Minimal (split containers)
make up-minimal         # build + start
make logs-minimal       # tail logs
make down-minimal       # stop + remove
make test-minimal       # provider ping + sanity test inside markitdown

# Local (run markitdown on host, provider in container)
make local-provider     # start bgutil-provider (docker)
make local-test         # run a quick local test against https://example.com

笔记：

  • MCP stdio的最小默认值。集 MCP_TRANSPORT=streamable-http 运行HTTP服务器。
  • 嵌入式始终使用HTTP streamable-http.
  • 集 YTDLP_POT_TRACE=true 在日志中启用yt-dlp PO令牌跟踪。

这将从以下两种情况之一开始：

  • 嵌入式：一个 markitdown 容器（8085上的MCP HTTP和4416上的bgutil提供程序内部）
  • 最小拆分：两个容器(markitdown 和 bgutil-provider)

MCP服务器可在以下网址访问http://localhost:8085/对于HTTP客户端。

传输模式配置

您可以使用环境变量配置传输模式：

# In compose under environment:
# Use stdio (minimal default)
- MCP_TRANSPORT=stdio

# Or use HTTP server with streaming-compatible transport
- MCP_TRANSPORT=streamable-http
- MCP_HTTP_PORT=8085  # only used when MCP_TRANSPORT=streamable-http

仅运行bgutil提供程序

如果您只想在本地开发设置中运行bgutil提供程序：

# Start only the bgutil provider (minimal compose)
cd docker/minimal && docker compose up bgutil-provider

# Or run it standalone
docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider

手动Docker构建

# Build the image
docker build -t mcp-markitdown .

# Run the container (Windows/Mac)
docker run -e OLLAMA_HOST=http://host.docker.internal:11434 mcp-markitdown

# Run the container (Linux)
docker run -e OLLAMA_HOST=http://172.17.0.1:11434 mcp-markitdown

# Test with a specific URL
docker run -e OLLAMA_HOST=http://host.docker.internal:11434 mcp-markitdown python main.py --test "https://example.com/document.pdf"

环境变量

  • OLLAMA_HOST：Ollama服务的URL（默认值：http://localhost:11434)
    • Windows/Mac： http://host.docker.internal:11434
    • Linux： http://172.17.0.1:11434 或使用 --network=host
  • YTDLP_BGUTIL_POT_PROVIDER_URL：如果设置，markitdown将指示yt-dlp使用此URL处的bgutil提供程序。
    • 最小组合将其设置为 http://bgutil-provider:4416.
    • 本地开发人员可以使用 http://127.0.0.1:4416 当提供者在主机上运行时。
  • YTDLP_POT_TRACE：设置为 true 启用yt-dlp-PO令牌跟踪（调试有关令牌生成的消息）。

网络配置

Windows/Mac： 用途 host.docker.internal 连接到主机上的服务。

Linux： 需要特殊配置：

  • 使用 --network=host 共享主机网络
  • 或使用 172.17.0.1:11434 （Docker网桥网关IP）
  • 或添加 --add-host=host.docker.internal:host-gateway

Docker故障排除

  1. 连接被拒绝错误：确保Ollama在主机上运行并且可访问
  2. Linux网络：尝试不同的方法：
    # Option 1: Host networking
docker run --network=host mcp-markitdown

# Option 2: Bridge with gateway
docker run -e OLLAMA_HOST=http://172.17.0.1:11434 mcp-markitdown

# Option 3: Custom host mapping
docker run --add-host=host.docker.internal:host-gateway mcp-markitdown

许可证

该项目使用微软的markitdown软件包，该软件包受麻省理工学院许可。

相关 MCP