如何使用MarkItDown MCP将文档转换为Markdown？

处理文档不再仅仅是在人工智能项目中打开文件，而是要将混乱转化为清晰。PDF、PowerPoint 和 Word 等文档以各种形状和大小充斥着我们的工作流程。如今，从这些文档中检索结构化内容已成为一项艰巨的任务。微软的 Markitdown MCP（Markdown 转换协议）简化了这一工作。它能将各种文件转换为结构化的 Markdown 格式。这有助于开发人员和技术撰稿人改进文档工作流程。

本文将解释 Markitdown MCP 并展示其用法。我们将介绍 Markitdown MCP 服务器的设置，还将讨论该协议背景下的 MarkItDown。下文还将介绍如何使用 Markitdown MCP 服务器进行测试。

什么是MarkItDown MCP？

Markitdown MCP 为文档转换提供了一种标准方法。它是一种服务器端协议。它在后台使用微软的 MarkItdown 库。服务器托管一个 RESTful API。用户将 PDF 或 Word 文件等文档发送到该服务器。服务器随后处理这些文件。它使用高级解析和特定格式化规则。输出结果是保持原始文档结构的 Markdown 文本。

Markitdown MCP的主要功能

Markitdown MCP 服务器包含几个有用的功能：

• 宽格式支持：它可将 PDF、DOCX 和 PPTX 等常见文件转换为 Markdown。
• 结构保存：它使用各种方法来理解和维护文档布局，如标题和列表。
• 可配置输出：用户可以调整设置来控制最终的 Markdown 风格。
• 服务器运行：它以服务器进程的形式运行。这样就可以集成到自动化系统和云设置中。

Markdown在工作流程中的作用

Markdown 是一种流行的文档格式。它的语法简单，易于读写。许多平台（如 GitHub）都很好地支持它。静态网站生成器也经常使用它。手动将其他格式转换为 Markdown 需要时间。Markitdown MCP 可自动完成这种转换。这样做的好处显而易见：

• 高效的内容处理：将源文件转换为可用的 Markdown。
• 一致的协作：标准格式有助于团队共同处理文档。
• 流程自动化：将文档转换纳入更大的自动化工作流程。

为集成设置 Markitdown MCP 服务器

如 Github Repo 所述，我们可以使用 Docker Image 将 Markitdown MCP 服务器与 Claude、Windsurf、Cursor 等不同的客户端设置在一起。但在这里，我们将使用LangChain 的 MCP 适配器创建一个本地 MCP 客户端。我们需要运行服务器，以便与 LangChain 配合使用。服务器支持不同的运行模式。

安装

首先，安装所需的 Python 软件包。

pip install markitdown-mcp langchain langchain_mcp_adapters langgraph langchain_groq

服务器配置

使用 STDIO 模式运行 Markitdown MCP 服务器。该模式连接标准输入和输出流。它非常适合基于脚本的集成。在终端直接运行以下内容。

markitdown-mcp

服务器开始运行时会发出一些警告。

我们还可以使用 SSE（服务器发送事件）模式。这种模式适合网络应用程序或长期运行的连接。在设置 Markitdown MCP 服务器以测试特定场景时，它也非常有用。

markitdown-mcp --sse --host 127.0.0.1 --port 3001

选择适合您的集成计划的模式。通过 STDIO 使用服务器进行本地测试通常是一个好的开始。我们建议在本文中使用 STDIO 模式。

使用 Markitdown MCP 进行 Markdown 转换

在上一篇文章《如何使用 LangChain 创建 MCP 客户端服务器》中，我们已经介绍了如何使用 LangChain 在本地构建 MCP 服务器和客户端设置。

本节将介绍如何将 LangChain 与 Markitdown MCP 服务器结合使用。它能自动将 PDF 文件转换为 Markdown 文件。该示例通过 ChatGroq 使用了 Groq 的 LLaMA 模型。请确保将 Groq API 密钥设置为环境变量，或直接将其传递给 ChatGroq。

第 1 步：首先导入必要的库。

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools
from langgraph.prebuilt import create_react_agent
import asyncio
from langchain_groq import ChatGroq

第 2 步：免费初始化Groq LLM。

您可以在此处找到 API 密钥：Groq API Key

# Initialize Groq model
model = ChatGroq(model="meta-llama/llama-4-scout-17b-16e-instruct", api_key="YOUR_API_KEY")

第 3 步：配置MCP服务器

我们在这里使用 StdioServerParameters，并直接使用已安装的 Markitdown MCP 软件包

server_params = StdioServerParameters(
   command="markitdown-mcp",
   args=[]  # No additional arguments needed for STDIO mode
)

第 4 步：现在，定义异步函数

load_mcp_tools 提供了 LangChain 与 Markitdown MCP 交互的函数。然后创建 ReAct 代理，并使用模型和 MCP 工具。代码会为 PDF 创建 file_uri，并发送提示，要求代理使用 MCP 转换文件。

async def run_conversion(pdf_path: str):
   async with stdio_client(server_params) as (read, write):
       async with ClientSession(read, write) as session:
           await session.initialize()
           print("MCP Session Initialized.")
           # Load available tools
           tools = await load_mcp_tools(session)
           print(f"Loaded Tools: {[tool.name for tool in tools]}")
           # Create ReAct agent
           agent = create_react_agent(model, tools)
           print("ReAct Agent Created.")
           # Prepare file URI (convert local path to file:// URI)
           file_uri = f"file://{pdf_path}"
           # Invoke agent with conversion request
           response = await agent.ainvoke({
               "messages": [("user", f"Convert {file_uri} to markdown using Markitdown MCP just return the output from MCP server")]
           })
           # Return the last message content
           return response["messages"][-1].content

第 5 步：该代码调用run_conversion函数

我们正在调用并从响应中提取 Markdown。它将内容保存到 pdf.md，最后在终端中打印输出。

if __name__ == "__main__":
   pdf_path = "/home/harsh/Downloads/LLM Evaluation.pptx.pdf"  # Use absolute path
   result = asyncio.run(run_conversion(pdf_path))
   with open("pdf.md", 'w') as f:
      f.write(result)
   print("\nMarkdown Conversion Result:")
   print(result)

输出

完整代码

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools
from langgraph.prebuilt import create_react_agent
import asyncio
from langchain_groq import ChatGroq
# Initialize Groq model
model = ChatGroq(model="meta-llama/llama-4-scout-17b-16e-instruct", api_key="")
# Configure MCP server
server_params = StdioServerParameters(
   command="markitdown-mcp", 
   args=[]  # No additional arguments needed for STDIO mode
)
async def run_conversion(pdf_path: str):
   async with stdio_client(server_params) as (read, write):
       async with ClientSession(read, write) as session:
           await session.initialize()
           print("MCP Session Initialized.")
           # Load available tools
           tools = await load_mcp_tools(session)
           print(f"Loaded Tools: {[tool.name for tool in tools]}")
           # Create ReAct agent
           agent = create_react_agent(model, tools)
           print("ReAct Agent Created.")
           # Prepare file URI (convert local path to file:// URI)
           file_uri = f"file://{pdf_path}"
           # Invoke agent with conversion request
           response = await agent.ainvoke({
               "messages": [("user", f"Convert {file_uri} to markdown using Markitdown MCP just retrun the output from MCP server")]
           })
           # Return the last message content
           return response["messages"][-1].content
if __name__ == "__main__":
   pdf_path = "/home/harsh/Downloads/LLM Evaluation.pdf"  # Use absolute path
   result = asyncio.run(run_conversion(pdf_path))
   with open("pdf.md", 'w') as f:
       f.write(result)
   print("\nMarkdown Conversion Result:")
   print(result)

检查输出

脚本会生成一个 pdf.md 文件。该文件包含输入 PDF 的 Markdown 版本。转换质量取决于原始文档的结构。Markitdown MCP 通常会保留以下元素：

• 标题（不同级别）
• 段落文本
• 列表（项目和编号）
• 表格（转换为 Markdown 语法）
• 代码块

输出

在输出中，我们可以看到它成功地检索到了标题、内容以及 Markdown 格式的普通文本。

因此，运行本地服务器进行测试有助于评估不同的文档类型。

LLM管道中的实际用例

集成 Markitdown MCP 可以改进多个人工智能工作流程：

• 知识库构建：将文档转换为 Markdown。将这些内容纳入知识库或 RAG 系统。
• LLM 内容准备：将源文件转换为 Markdown。为 LLM 总结或分析任务准备一致的输入内容。
• 文档数据提取：将带表格的文档转换为 Markdown。这可简化结构化数据的解析。
• 文档自动化：生成技术手册。将 Word 文档等源文件转换为 Markdown，用于静态网站生成器。

小结

Markitdown MCP 提供了一种功能强大、基于服务器的文档转换方法。它能处理多种格式。它能生成结构化的 Markdown 输出。将其与 LLM 集成可实现文档处理任务的自动化。这种方法支持可扩展的文档实践。使用服务器进行测试可直接进行评估。通过在这些工作流程中的实际应用，我们可以更好地理解 MarkItDown 的MCP。

请访问 Markitdown MCP GitHub 代码仓库了解更多信息。

常见问题

Q1. Markitdown MCP 的主要功能是什么？

答：Markitdown MCP 可将 PDF 和 Word 等文档转换为结构化的 Markdown。它使用基于服务器的协议来完成这项任务。

Q2. Markitdown MCP 服务器可以处理哪些文件格式？

答：服务器可处理 PDF、DOCX、PPTX 和 HTML 文件。根据核心库的不同，还可能支持其他格式。

Q3. LangChain 如何使用 Markitdown MCP？

答：LangChain 使用特殊工具与服务器通信。代理可以通过该服务器请求文档转换。

Q4. Markitdown MCP 是开源的吗？

回答：是的，它是微软的开源软件。用户需承担任何服务器托管费用。

Q5. 我可以运行 Markitdown MCP 服务器进行测试吗？

回答：可以，测试服务器可以在本地运行。使用 STDIO 或 SSE 模式进行开发和评估。