MCP Markitdown

MCP文档知识

提供方 bradleyjlevine

文档知识 stdio · 本地进程 无需鉴权 社区 / 第三方
查看接入方式

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

一句话选型结论

按资料字段整理

MCP Markitdown 属于文档知识类 MCP 服务器,stdio · 本地进程,无需鉴权,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 1 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量1暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

文档转换Python本地部署Markdown生成文件处理YouTube转录AI标注

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 1 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 1 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP Markitdown当前 1 stdio · 本地进程 本地部署 有 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方bradleyjlevine上游标注的维护方 bradleyjlevine
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

11.2 KB
来自项目仓库与上游目录的原文,未做删改

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后,运行以下命令之一以拉取受支持的模型:```bash
    ollama pull gemma3:4b

OR

ollama pull qwen2.5vl:7b


- 对于增强的YouTube转录提取,可以选择运行bgutil-ytdlp锅提供程序容器:```bash
# 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(推荐)```bash

Start both the MCP server and bgutil-provider

docker-compose up -d


#### 选项2:手动设置

1. (可选)要增强YouTube转录提取,请运行bgutil提供程序容器:```bash
docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider
  1. 运行MCP服务器:```bash

Default transport is now HTTP (port 8085)

uv run main.py

For stdio transport

MCP_TRANSPORT=stdio uv run main.py


3. 在本地运行时(不使用Docker Compose),设置bgutil提供程序URL,以便yt-dlp可以为YouTube使用SABR令牌:```bash
# 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")


答复:```json
{
"markdown": "# Document Title\n\nDocument content converted to markdown..."
}

测试特定URL

您可以使用以下命令在不启动MCP服务器的情况下测试文档转换 --test 标志:```bash
uv run main.py --test "https://example.com/document.pdf"


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

## YouTube转录功能

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

### 先进的提取方法

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

### 主要特点

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

### 响应格式示例```json
{
"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构建和运行:```bash

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包含在常见任务中:```bash
# 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客户端。

传输模式配置

您可以使用环境变量配置传输模式:```bash

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提供程序:```bash
# 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构建```bash

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在主机上运行并且可访问
1. **Linux网络**:尝试不同的方法:```bash
# 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软件包,该软件包受麻省理工学院许可。

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
MCP Markitdown 怎么安装?

在客户端按下面的安装命令接入:docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider。装完在客户端配置里引用同一个包或端点。

MCP Markitdown 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

MCP Markitdown 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP Markitdown 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

MCP Markitdown 能提供哪些能力?

资料显示约 1 个工具;能力标签包括 文档转换、文件处理、Python。具体工具清单以官方文档为准。

MCP Markitdown 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

MCP Markitdown 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。