1. 为什么我要把 MarkItDown 塞进 Docker 里跑MarkItDown 是微软开源的一个文档转 Markdown 工具能处理 PDF、Word、PPT、Excel、图片等十几种格式输出结构化的 Markdown 文本。它最适合的场景不是「精准还原排版」而是「快速把文档变成大模型能读的纯文本」——比如你有一堆技术 PDF想让 AI 帮你总结、问答、建轻量知识库MarkItDown 就是那个把原料喂进去的管道。但直接 pip install 在宿主机上跑有几个现实问题依赖冲突、magika 这类大包下载慢、换台机器就得重装一遍。所以我选择用 Docker 把它封起来一次构建到处运行。更进一步MarkItDown 官方提供了 MCP 服务版镜像可以接入 Cherry Studio 这类支持 MCP 协议的 AI 客户端让 AI 直接读取你本地的文档。这篇内容面向需要批量把 PDF/Office 文档转成 Markdown 的开发者交付三样东西可复制的 Docker 运行命令、MCP 配置骨架、Cherry Studio 侧的验证动作。中间会穿插我踩过的坑和排查方法你照着做基本能跑通。2. 前置准备TaoToken 与运行环境在开始之前先把两件事理清楚一是 AI 客户端侧要有一个能用的模型接入点二是 Docker 环境要就绪。模型接入这块我用的是 TaoToken 提供的 API 服务。它的作用是给 Cherry Studio 这类客户端提供一个统一的模型调用入口你不需要自己去折腾各种模型的接入配置。具体操作是先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建一个 API Key。这个 Key 后面要填到 Cherry Studio 的模型配置里。注意API Key 只在创建时完整显示一次记得当场复制保存。如果丢了就重新生成一个。Docker 环境方面LinuxCentOS/Ubuntu 都行或 Windows WSL2 都可以。确认 Docker 和 Docker Compose 已安装docker --version docker compose version如果这两条命令都能输出版本号环境就没问题。接下来拉取 MarkItDown 的 MCP 服务镜像。3. 可复制配置Docker 运行 MarkItDown MCP 服务3.1 拉取镜像与启动容器MarkItDown 官方在 Docker Hub 上提供了 MCP 服务版镜像mcp/markitdown。直接拉取docker pull mcp/markitdown:latest拉完之后启动容器。这里有个关键点容器必须绑定0.0.0.0否则 Cherry Studio 从宿主机或局域网访问时会连不上。docker run -d \ --name markitdown-mcp \ -p 3001:3001 \ -e HOST0.0.0.0 \ -e PORT3001 \ --restart unless-stopped \ mcp/markitdown:latest参数说明参数作用-p 3001:3001把容器 3001 端口映射到宿主机-e HOST0.0.0.0监听所有网卡允许外部连接-e PORT3001MCP 服务监听端口--restart unless-stopped开机自启避免每次手动拉起启动后确认容器状态docker ps | grep markitdown看到Up状态就说明服务在跑了。再验证一下端口是否在监听curl -s http://127.0.0.1:3001/sse如果返回 SSE 事件流相关内容可能是一段event: endpoint之类的文本说明 MCP 服务已经正常响应。3.2 如果你还需要命令行批量转换MCP 服务版镜像只支持 HTTP/SSE 接口调用不支持直接传文件路径做命令行转换。如果你同时需要批量命令行转换能力建议自己构建一个预装依赖的镜像FROM python:3.11-slim RUN pip install --no-cache-dir markitdown[all] -i https://pypi.tuna.tsinghua.edu.cn/simple WORKDIR /data ENTRYPOINT [markitdown]构建并打标签docker build -t my-markitdown:latest .之后批量转换就可以这样用docker run --rm -v /host/docs:/data my-markitdown:latest /data/input.pdf /host/docs/output.md这样两套能力互补MCP 服务版给 Cherry Studio 用命令行版给脚本批量处理用。4. 验证请求接入 Cherry Studio 并测试转换4.1 Cherry Studio 侧配置 MCP打开 Cherry Studio进入设置 → MCP 服务器添加一个新的 MCP 服务。配置骨架如下{ mcpServers: { markitdown: { type: sse, url: http://192.168.108.66:3001/sse } } }把192.168.108.66换成你 Docker 宿主机的实际 IP。如果 Cherry Studio 和 Docker 在同一台机器上用127.0.0.1也行。保存后 Cherry Studio 会尝试连接连接成功后 MCP 服务列表里会显示 markitdown 为已连接状态。4.2 模型配置在 Cherry Studio 的模型设置里填入 TaoToken 的 API 地址和刚才创建的 Key。API 地址是https://taotoken.net/api模型选择你需要的对话模型。配置完成后在对话界面选择这个模型就可以开始测试了。4.3 实际验证动作在 Cherry Studio 新建一个对话输入类似这样的指令请用 markitdown 工具读取 /data/test.pdf 并总结内容如果一切正常AI 会调用 MCP 工具去读取文件然后返回总结结果。这一步能跑通说明整条链路——Docker 容器 → MCP 服务 → Cherry Studio → 模型——全部打通了。提示文件路径要填容器内能访问到的路径。如果你启动容器时没有挂载宿主机目录容器里是看不到宿主机文件的。需要加-v /host/docs:/data把目录挂进去。5. 本篇常见错误排查5.1 容器启动后 Cherry Studio 连不上最常见的原因是容器只绑定了127.0.0.1。检查启动命令里有没有-e HOST0.0.0.0。另外确认宿主机防火墙放行了 3001 端口# CentOS 7 firewall-cmd --add-port3001/tcp --permanent firewall-cmd --reload如果是云服务器安全组也要放行对应端口。5.2 转换结果为空或内容残缺MarkItDown 对扫描版 PDF、图片型文档没有 OCR 能力这类文件解析出来基本是空的。另外复杂排版多栏、大量表格、图文混排的还原度也有限。如果你需要高精度转换建议搭配 MinerU、Nougat 这类专业工具使用。5.3 命令行转换时日志混入输出文件用命令行版镜像时pip 安装日志、字体警告等会混进标准输出。解决办法是重定向docker run --rm -v /host/docs:/data my-markitdown:latest /data/input.pdf /host/docs/output.md 2/dev/null这样只有纯 Markdown 内容会写入文件。5.4 文件名含空格或中文导致转换失败写批量脚本时遍历文件要用安全方式find /data -name *.pdf -print0 | while IFS read -r -d file; do docker run --rm -v /host/docs:/data my-markitdown:latest $file ${file%.pdf}.md 2/dev/null done所有变量加双引号用find -print0read -d 组合能兼容任意文件名。5.5 MCP 服务连接超时先确认容器还在运行docker ps。如果容器频繁重启看日志docker logs markitdown-mcp --tail 50常见原因是端口被占用。换一个端口重新启动即可。6. 后续怎么用从验证到长期编码整条链路跑通之后你有两种用法。一种是轻量场景在 Cherry Studio 里直接对话让 AI 读取本地文档做总结、问答、提取要点。这种方式适合个人知识管理、快速阅读。另一种是长期编码或 Agent 场景如果你需要把文档转换能力集成到自动化流程里或者让 AI 持续处理大量文档可以考虑 TaoToken 的 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配合 API 做批量调用。API Key 管理在控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你只是想先验证模型对话效果可以直接用模型对话入口 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速试一下。Claude Code 相关的接入配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。实测下来MarkItDown 的定位很清晰它不是专业文档转换工具而是面向大模型的轻量预解析管道。纯文本类 PDF、简单 Word 文档转换成功率高适合 AI 辅助阅读和轻量归档复杂技术手册、扫描件就别指望它了该上 OCR 就上 OCR该换工具就换工具。把 Docker 镜像固化好、MCP 服务配成自启动日常用起来基本不用再操心。
【github爆款】MarkItDown 部署与测评报告：Docker 镜像 + MCP 接入 Cherry Studio 全流程
1. 为什么我要把 MarkItDown 塞进 Docker 里跑MarkItDown 是微软开源的一个文档转 Markdown 工具能处理 PDF、Word、PPT、Excel、图片等十几种格式输出结构化的 Markdown 文本。它最适合的场景不是「精准还原排版」而是「快速把文档变成大模型能读的纯文本」——比如你有一堆技术 PDF想让 AI 帮你总结、问答、建轻量知识库MarkItDown 就是那个把原料喂进去的管道。但直接 pip install 在宿主机上跑有几个现实问题依赖冲突、magika 这类大包下载慢、换台机器就得重装一遍。所以我选择用 Docker 把它封起来一次构建到处运行。更进一步MarkItDown 官方提供了 MCP 服务版镜像可以接入 Cherry Studio 这类支持 MCP 协议的 AI 客户端让 AI 直接读取你本地的文档。这篇内容面向需要批量把 PDF/Office 文档转成 Markdown 的开发者交付三样东西可复制的 Docker 运行命令、MCP 配置骨架、Cherry Studio 侧的验证动作。中间会穿插我踩过的坑和排查方法你照着做基本能跑通。2. 前置准备TaoToken 与运行环境在开始之前先把两件事理清楚一是 AI 客户端侧要有一个能用的模型接入点二是 Docker 环境要就绪。模型接入这块我用的是 TaoToken 提供的 API 服务。它的作用是给 Cherry Studio 这类客户端提供一个统一的模型调用入口你不需要自己去折腾各种模型的接入配置。具体操作是先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建一个 API Key。这个 Key 后面要填到 Cherry Studio 的模型配置里。注意API Key 只在创建时完整显示一次记得当场复制保存。如果丢了就重新生成一个。Docker 环境方面LinuxCentOS/Ubuntu 都行或 Windows WSL2 都可以。确认 Docker 和 Docker Compose 已安装docker --version docker compose version如果这两条命令都能输出版本号环境就没问题。接下来拉取 MarkItDown 的 MCP 服务镜像。3. 可复制配置Docker 运行 MarkItDown MCP 服务3.1 拉取镜像与启动容器MarkItDown 官方在 Docker Hub 上提供了 MCP 服务版镜像mcp/markitdown。直接拉取docker pull mcp/markitdown:latest拉完之后启动容器。这里有个关键点容器必须绑定0.0.0.0否则 Cherry Studio 从宿主机或局域网访问时会连不上。docker run -d \ --name markitdown-mcp \ -p 3001:3001 \ -e HOST0.0.0.0 \ -e PORT3001 \ --restart unless-stopped \ mcp/markitdown:latest参数说明参数作用-p 3001:3001把容器 3001 端口映射到宿主机-e HOST0.0.0.0监听所有网卡允许外部连接-e PORT3001MCP 服务监听端口--restart unless-stopped开机自启避免每次手动拉起启动后确认容器状态docker ps | grep markitdown看到Up状态就说明服务在跑了。再验证一下端口是否在监听curl -s http://127.0.0.1:3001/sse如果返回 SSE 事件流相关内容可能是一段event: endpoint之类的文本说明 MCP 服务已经正常响应。3.2 如果你还需要命令行批量转换MCP 服务版镜像只支持 HTTP/SSE 接口调用不支持直接传文件路径做命令行转换。如果你同时需要批量命令行转换能力建议自己构建一个预装依赖的镜像FROM python:3.11-slim RUN pip install --no-cache-dir markitdown[all] -i https://pypi.tuna.tsinghua.edu.cn/simple WORKDIR /data ENTRYPOINT [markitdown]构建并打标签docker build -t my-markitdown:latest .之后批量转换就可以这样用docker run --rm -v /host/docs:/data my-markitdown:latest /data/input.pdf /host/docs/output.md这样两套能力互补MCP 服务版给 Cherry Studio 用命令行版给脚本批量处理用。4. 验证请求接入 Cherry Studio 并测试转换4.1 Cherry Studio 侧配置 MCP打开 Cherry Studio进入设置 → MCP 服务器添加一个新的 MCP 服务。配置骨架如下{ mcpServers: { markitdown: { type: sse, url: http://192.168.108.66:3001/sse } } }把192.168.108.66换成你 Docker 宿主机的实际 IP。如果 Cherry Studio 和 Docker 在同一台机器上用127.0.0.1也行。保存后 Cherry Studio 会尝试连接连接成功后 MCP 服务列表里会显示 markitdown 为已连接状态。4.2 模型配置在 Cherry Studio 的模型设置里填入 TaoToken 的 API 地址和刚才创建的 Key。API 地址是https://taotoken.net/api模型选择你需要的对话模型。配置完成后在对话界面选择这个模型就可以开始测试了。4.3 实际验证动作在 Cherry Studio 新建一个对话输入类似这样的指令请用 markitdown 工具读取 /data/test.pdf 并总结内容如果一切正常AI 会调用 MCP 工具去读取文件然后返回总结结果。这一步能跑通说明整条链路——Docker 容器 → MCP 服务 → Cherry Studio → 模型——全部打通了。提示文件路径要填容器内能访问到的路径。如果你启动容器时没有挂载宿主机目录容器里是看不到宿主机文件的。需要加-v /host/docs:/data把目录挂进去。5. 本篇常见错误排查5.1 容器启动后 Cherry Studio 连不上最常见的原因是容器只绑定了127.0.0.1。检查启动命令里有没有-e HOST0.0.0.0。另外确认宿主机防火墙放行了 3001 端口# CentOS 7 firewall-cmd --add-port3001/tcp --permanent firewall-cmd --reload如果是云服务器安全组也要放行对应端口。5.2 转换结果为空或内容残缺MarkItDown 对扫描版 PDF、图片型文档没有 OCR 能力这类文件解析出来基本是空的。另外复杂排版多栏、大量表格、图文混排的还原度也有限。如果你需要高精度转换建议搭配 MinerU、Nougat 这类专业工具使用。5.3 命令行转换时日志混入输出文件用命令行版镜像时pip 安装日志、字体警告等会混进标准输出。解决办法是重定向docker run --rm -v /host/docs:/data my-markitdown:latest /data/input.pdf /host/docs/output.md 2/dev/null这样只有纯 Markdown 内容会写入文件。5.4 文件名含空格或中文导致转换失败写批量脚本时遍历文件要用安全方式find /data -name *.pdf -print0 | while IFS read -r -d file; do docker run --rm -v /host/docs:/data my-markitdown:latest $file ${file%.pdf}.md 2/dev/null done所有变量加双引号用find -print0read -d 组合能兼容任意文件名。5.5 MCP 服务连接超时先确认容器还在运行docker ps。如果容器频繁重启看日志docker logs markitdown-mcp --tail 50常见原因是端口被占用。换一个端口重新启动即可。6. 后续怎么用从验证到长期编码整条链路跑通之后你有两种用法。一种是轻量场景在 Cherry Studio 里直接对话让 AI 读取本地文档做总结、问答、提取要点。这种方式适合个人知识管理、快速阅读。另一种是长期编码或 Agent 场景如果你需要把文档转换能力集成到自动化流程里或者让 AI 持续处理大量文档可以考虑 TaoToken 的 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配合 API 做批量调用。API Key 管理在控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你只是想先验证模型对话效果可以直接用模型对话入口 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速试一下。Claude Code 相关的接入配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。实测下来MarkItDown 的定位很清晰它不是专业文档转换工具而是面向大模型的轻量预解析管道。纯文本类 PDF、简单 Word 文档转换成功率高适合 AI 辅助阅读和轻量归档复杂技术手册、扫描件就别指望它了该上 OCR 就上 OCR该换工具就换工具。把 Docker 镜像固化好、MCP 服务配成自启动日常用起来基本不用再操心。
