使用 MarkItDown MCP Server 将文档与网页内容一键转换为 MarkdownKlavis 集成实战指南【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis导读本文围绕 Klavis 开源仓库中mcp_servers/markitdown目录所实现的 MarkItDown MCP Server讲解如何通过托管服务或 Docker 自托管两种方式快速搭建文档转 Markdown 的 MCP 工具并深入剖析其唯一的convert_document_to_markdown工具的参数契约、底层转换流程与双传输SSE / StreamableHTTP架构。读完本文你将掌握该服务的部署命令、调用方式、支持的文件格式范围与可调参数并能够从源码层面理解其工作原理为 AI Agent 接入可靠的文档解析能力提供直接参考。MarkItDown 与 MCP为什么需要这样一座转换桥MarkItDown 是一个将 PDF、Office 文档、HTML、EPUB 等各类格式转换为干净 Markdown 的转换引擎。但单独的转换库无法直接被 AI Agent 使用——Agent 需要通过 Model Context ProtocolMCP 以标准化的工具形式发现并调用能力。本仓库中的 markitdown MCP Server 正是这座桥梁它把 MarkItDown 的转换能力封装为一个标准的 MCP 工具让任何 MCP 客户端Claude、Cursor 等或通过 Klavis 平台接入的 AI 应用都能用统一的uri参数把远程资源转换成 Markdown 文本。从 服务端指令文本 可以看到该服务官方支持的文件类型包括PDF、PowerPoint、Word、Excel、HTML、基于文本的格式CSV、JSON、XML、ZIP 压缩包会迭代遍历包内内容、EPUB 电子书。这意味着一个工具即可覆盖日常工作中绝大多数文档转纯文本/结构化 Markdown 的场景。快速上手两种接入方式方式一使用 Klavis 托管服务推荐生产环境如果不想自行维护基础设施可以直接通过 Klavis 的托管基础设施获取 MarkItDown 能力无需任何配置。官方推荐流程分为两步第一步安装 Klavis SDKpip install klavis # 或 npm install klavis第二步在代码中创建 MCP Server 实例from klavis import Klavis klavis Klavis(api_keyyour-free-key) server klavis.mcp_server.create_server_instance(MARKITDOWN, user123)这里MARKITDOWN是托管平台上该 MCP Server 的服务标识user123是用于隔离会话的用户标识。托管方式特别适合生产环境你无需关心底层进程、Docker 容器与端口映射只需要一个 API Key 即可获得即时访问。方式二使用 Docker 自托管本地部署对于需要数据私密性、离线运行或想完全掌控运行环境的场景仓库提供了完整的 Docker 镜像方案# 拉取最新镜像 docker pull ghcr.io/klavis-ai/markitdown-mcp-server:latest # 运行 MarkItDown MCP Server无需认证 docker run -p 5000:5000 \ ghcr.io/klavis-ai/markitdown-mcp-server:latest无需认证MarkItDown 的文档转换本身不依赖外部第三方 API因此服务默认不要求任何身份验证docker run后即可直接使用。该镜像的构建方式记录在 Dockerfile 中关键点包括基于python:3.12-slim并安装gcc以满足部分转换依赖的编译需要先复制requirements.txt再安装依赖充分利用 Docker 层缓存加速后续构建暴露5000端口与默认服务端口一致启动命令为python server.py。深入工具convert_document_to_markdown无论通过哪种方式接入该服务对外暴露的 MCP 工具只有一个convert_document_to_markdown。其定义位于 server.py 的 list_tools 回调输入参数契约如下参数类型必填说明uristring是待转换资源的 HTTP/HTTPS 地址资源类型必须是支持列表中的一种PDF、PowerPoint、Word、Excel、HTML、文本类格式CSV、JSON、XML、ZIP迭代遍历包内内容、EPUB工具还带有两个注解annotationscategory: MARKITDOWN_CONVERT用于归类readOnlyHint: True表明该工具是只读操作、不会产生副作用这有助于客户端在并行执行或安全审计时做出更合理的调度决策。调用流程与参数校验工具的完整处理逻辑位于 call_tool 回调校验参数若调用时缺少uri直接返回Error: URI parameter is required文本内容执行转换调用convert_document_to_markdown(uri)并将结果包装为types.TextContent返回异常兜底任何转换异常都会被捕获并记录日志logger.exception同时以Error: {str(e)}的形式返回给客户端避免 Agent 进程崩溃。从调用方视角看返回值始终是纯文本的 Markdown 内容符合 MCP 的TextContent标准客户端无需解析复杂结构即可直接使用。底层转换原理核心函数convert_document_to_markdown的实现位于 server.py其转换链路值得拆解async def convert_document_to_markdown(uri: str) - str: if not uri.startswith(http) and not uri.startswith(https): return fUnsupported uri. Only http:, https: are supported. response requests.get(uri) if response.status_code 200: with tempfile.NamedTemporaryFile( suffix.pdf, deleteTrue, delete_on_closeTrue ) as temp_file: temp_file.write(response.content) temp_path temp_file.name return MarkItDown().convert_uri(ffile://{temp_path}).markdown return fFailed to download the resource. Status code: {response.status_code}几个值得注意的工程细节协议白名单只接受http:与https:前缀的 URI其他协议如file:、ftp:一律拒绝从入口处规避了本地文件读取类安全问题两步转换先用requests.get(uri)将远程资源下载到内存再写入一个带.pdf后缀的临时文件最后通过MarkItDown().convert_uri(ffile://{temp_path})完成转换并读取.markdown属性。以file://方式喂给 MarkItDown是为了让转换器能够按本地文件路径正确嗅探 MIME 类型与格式临时文件自动清理NamedTemporaryFile配合delete_on_closeTrue转换完成后临时文件随即销毁不会在磁盘上残留敏感文档副本下载失败可观测非 200 状态码会返回具体的 HTTP 状态码便于客户端判断失败原因如 404、403。这一远程下载 → 落临时文件 → 本地转换的模式也印证了 mcp-clients 客户端实现 中对markitdown.markitdown(pdf_bytes)的同类用法——PDF 二进制内容被直接转换为 Markdown 文本二者形成服务端与客户端互补的转换能力。依赖与运行环境requirements.txt 明确列出了运行该服务所需的依赖mcp1.11.0 markitdown[all] pydantic fastapi uvicorn[standard]mcp1.11.0锁定 MCP Python SDK 版本保证协议行为一致markitdown[all]安装 MarkItDown 及其全部转换扩展覆盖 PDF、Office、HTML、EPUB 等所有受支持格式pydantic用于 MCP 工具输入参数的模式校验Field、Annotatedfastapiuvicorn[standard]支撑 ASGI 服务与 HTTP 传输层。在 mcp-clients 的 pyproject.toml 中同样声明了markitdown[all]依赖说明整个仓库体系内 MarkItDown 同时扮演着独立 MCP 服务与客户端内置解析器双重角色。架构解析双传输协议与可配置项与仓库内其他 MCP Server 一致该服务基于 MCP Python SDK 的Server低层 API 构建并同时挂载了两种传输方式见 server.py 路由注册传输方式端点说明SSEGET /sse传统 SSE 流式传输配合POST /messages/用于客户端回发消息StreamableHTTPPOST /mcp基于 HTTP 的流式协议以无状态模式运行其中 StreamableHTTP 通过StreamableHTTPSessionManager实现当前以无状态stateless模式运行event_storeNone见 server.py即每次请求不保留跨会话事件状态部署更简单、水平扩展更友好。启动参数与环境变量服务入口main函数通过 Click 提供三个命令行参数见 server.py参数默认值说明--port5000受环境变量MARKITDOWN_MCP_SERVER_PORT控制HTTP 监听端口--log-levelINFO日志级别可选DEBUG、INFO、WARNING、ERROR、CRITICAL--json-responseFalseflag启用后 StreamableHTTP 以 JSON 响应替代 SSE 流其中端口默认值并非硬编码服务在启动时会优先读取环境变量MARKITDOWN_MCP_SERVER_PORT未设置时才回退到5000见 server.py。因此在 Docker 部署中可通过-e MARKITDOWN_MCP_SERVER_PORT8080灵活覆盖端口无需改动代码。启动后服务会打印出两个可访问的端点Server starting on port 5000 with dual transports: - SSE endpoint: http://localhost:5000/sse - StreamableHTTP endpoint: http://localhost:5000/mcpMCP 客户端既可以选择兼容性更广的 SSE 端点也可以选择现代 StreamableHTTP 端点两者共享同一个markitdown-mcp-serverServer 实例与工具注册表。与 MCP 客户端的协作方式该服务与仓库中的 mcp-clients 模块配合使用时遵循统一的接入模式客户端通过create_server_instance(MARKITDOWN, user123)托管方式或连接本地 Docker 端点自托管方式建立会话随后 MCP 客户端内部会为每个server_id维护独立会话、缓存工具列表见 mcp_client.py 的会话管理逻辑并通过list_tools发现convert_document_to_markdown后即可调用。一个典型调用场景是Agent 在对话中收到一个指向 PDF 报告或 HTML 页面的 URL调用convert_document_to_markdown获得干净 Markdown 后将其作为上下文继续推理——整个过程对 Agent 而言是透明的、标准化的无需关心文件格式差异。参与贡献与许可该服务与整个仓库遵循相同的开源治理规范贡献前请阅读仓库根目录的 CONTRIBUTING.md代码以 Apache 2.0 协议发布详见根目录 LICENSE。如需为 MarkItDown MCP Server 增加格式支持、优化临时文件处理或扩展传输选项可直接从 server.py 入手——其结构清晰、职责单一是理解把现有 Python 库封装为 MCP 工具这一通用模式的良好范本。小结MarkItDown MCP Server 是一个小而精的工具型服务托管方式一条create_server_instance(MARKITDOWN, ...)即可接入自托管方式一条docker run即可启动它把 MarkItDown 的多格式转换能力收敛为一个标准、只读、带参数校验的 MCP 工具并通过 SSE 与 StreamableHTTP 双传输同时服务新旧客户端。对于需要让 AI Agent 稳定读取 PDF、Office、HTML、EPUB 等异构文档的团队这一实现提供了开箱即用且可深度定制的可靠方案。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考