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）公开功能
设置和安装
- 确保您安装了Python 3.11或更高版本
- 如果尚未安装uv包管理器，请安装：
pip install uv - 安装依赖项：
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：手动设置
- （可选）要增强YouTube转录提取，请运行bgutil提供程序容器：
docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider- 运行MCP服务器：
# Default transport is now HTTP (port 8085)
uv run main.py
# For stdio transport
MCP_TRANSPORT=stdio uv run main.py- 在本地运行时（不使用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 （当地）。显式设置变量可确保行为一致。
- 使用
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转录提取功能：
先进的提取方法
- 主要的，重要的 用于快速、高效提取的youtube转录api
- 退路： yt-dlp用于屏蔽视频的字幕解析
- 增强： 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
运作原理
- 服务器接受指向文档的URL
- 对于YouTube网址：
- 尝试使用youtube转录api提取转录 - 如果API失败，则返回到带有字幕提取的yt-dlp - 使用bgutil-ytdlp提供程序绕过YouTube的SABR保护（如果可用） - 自动消除副本行 - 包括视频元数据（标题、上传者、持续时间、描述） - 支持对大型成绩单进行分页
- 对于图像： 如果Ollama有支持的型号（gemma3:4b或qwen2.5vl:7b），它会生成一个描述性标题
- 其他文件： 下载到临时位置并使用Microsoft的markitdown包进行转换
- 文档转换为markdown格式，保留结构
- 临时文件已清理
- 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。
- 克隆存储库并导航到项目目录
- 使用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故障排除
- 连接被拒绝错误：确保Ollama在主机上运行并且可访问
- 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软件包，该软件包受麻省理工学院许可。