MarkItDown MCP Can Convert Any Document into Markdowns!

Handling documents is no longer just about opening files in your AI projects, it’s about transforming chaos into clarity. Docs such as PDFs, PowerPoints, and Word flood our workflows in every shape and size. Retrieving structured content from these documents has become a big task today. Markitdown MCP (Markdown Conversion Protocol) from Microsoft simplifies this. It converts various files into structured Markdown format. This helps developers and technical writers improve documentation workflows. This article explains Markitdown MCP and shows its usage. We will cover setting up the Markitdown MCP server and will also discuss MarkItDown in the context of this protocol. Using the Markitdown mcp server for testing is also covered below.

Table of contents

• What is MarkItDown MCP?
  • Key Features of Markitdown MCP
• The Role of Markdown in Workflows
• Setting Up the Markitdown MCP Server for Integration
  • Installation
  • Server Configuration
• Markdown Conversion with Markitdown MCP
  • Step 1: Import the necessary libraries first.
  • Step 2: Initialize the Groq LLM, it’s free of cost. You can find the API key here
  • Step 3: Configure the MCP server
  • Step 4: Now, define the Asynchronous function
  • Step 5: This code calls the run_conversion function
• Practical Use Cases in LLM Pipelines
• Conclusion
• Frequently Asked Questions

What is MarkItDown MCP?

Markitdown MCP offers a standard method for document conversion. It acts as a server-side protocol. It uses Microsoft’s MarkItdown library in the backend. The server hosts a RESTful API. Users send documents like PDFs or Word files to this server. The server then processes these files. It uses advanced parsing and specific formatting rules. The output is Markdown text that keeps the original document structure.

Key Features of Markitdown MCP

The Markitdown MCP server includes several useful features:

• Wide Format Support: It converts common files like PDF, DOCX, and PPTX to Markdown.
• Structure Preservation: It uses methods to understand and maintain document layouts like headings and lists.
• Configurable Output: Users can adjust settings to control the final Markdown style.
• Server Operation: It runs as a server process. This allows integration into automated systems and cloud setups.

The Role of Markdown in Workflows

Markdown is a popular format for documentation. Its simple syntax makes it easy to read and write. Many platforms like GitHub support it well. Static site generators often use it. Converting other formats to Markdown manually takes time. Markitdown MCP automates this conversion. This provides clear benefits:

• Efficient Content Handling: Transform source documents into usable Markdown.
• Consistent Collaboration: Standard format helps teams work together on documents.
• Process Automation: Include document conversion within larger automated workflows.

Setting Up the Markitdown MCP Server for Integration

We can set up the Markitdown MCP server with different clients like Claude, Windsurf, Cursor using Docker Image as mentioned in the Github Repo. But here we will be creating a local MCP client using LangChain’s MCP Adaptors. We need a running the server to use it with LangChain. The server supports different running modes.

Installation

First, install the required Python packages.

pip install markitdown-mcp langchain langchain_mcp_adapters langgraph langchain_groq

Server Configuration

Run the Markitdown MCP server using STDIO mode. This mode connects standard input and output streams. It works well for script-based integration. Directly run the following in the terminal.

markitdown-mcp

The server will start running with some warnings.

We can also use SSE (Server-Sent Events) mode. This mode suits web applications or long-running connections. It is also useful when setting up a Markitdown MCP server for testing specific scenarios.

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

Select the mode that fits your integration plan. Using the the server for testing locally via STDIO is often a good start. We recommend using STDIO mode for this article.

Markdown Conversion with Markitdown MCP

We have already covered how to build an MCP server and client setup locally using LangChain in our previous blog MCP Client Server Using LangChain.

Now, this section shows how to use LangChain with the Markitdown MCP server. It automates the conversion of a PDF file to Markdown. The example employs Groq’s LLaMA model through ChatGroq. Make sure to set up the Groq API key as an environment variable or pass it directly to ChatGroq.

Step 1: Import the necessary libraries first.

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

Step 2: Initialize the Groq LLM, it’s free of cost. You can find the API key here

Here’s the Groq API Key: Groq API Key

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

Step 3: Configure the MCP server

We are using StdioServerParameters, and directly using the installed Markitdown MCP package here

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

Step 4: Now, define the Asynchronous function

This will take the PDF path as the input, ClientSession starts communication. load_mcp_tools provides functions for LangChain interaction with Markitdown MCP. Then a ReAct agent is created, It uses the model and the MCP tools. The code creates a file_uri for the PDF and sends a prompt asking the agent to convert the file using 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

Step 5: This code calls the run_conversion function

We are calling and extracting Markdown from the response. It saves the content to pdf.md, and finally prints the output in the terminal.

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)

Output

Full Code

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)

Examining the Output

The script generates a pdf.md file. This file holds the Markdown version of the input PDF. The conversion quality depends on the original document’s structure. Markitdown MCP usually preserves elements like:

• Headings (various levels)
• Paragraph text
• Lists (bulleted and numbered)
• Tables (converted to Markdown syntax)
• Code blocks

Output

Here in the output, we can see that it successfully retrieved the headings, contents, as well as normal text in markdown format.

Hence, running a local server for testing helps evaluate different document types.

Also watch:

Practical Use Cases in LLM Pipelines

Integrating Markitdown MCP can improve several AI workflows:

• Knowledge Base Building: Convert documents into Markdown. Ingest this content into knowledge bases or RAG systems.
• LLM Content Preparation: Transform source files into Markdown. Prepare consistent input for LLM summarization or analysis tasks.
• Document Data Extraction: Convert documents with tables into Markdown. This simplifies parsing structured data.
• Documentation Automation: Generate technical manuals. Convert source files like Word documents into Markdown for static site generators.

Conclusion

Markitdown MCP provides a capable, server-based method for document conversion. It handles multiple formats. It produces structured Markdown output. Integrating it with LLMs enables automation of document processing tasks. This approach supports scalable documentation practices. Using the the server for testing makes evaluation straightforward. MarkItDown’s MCP is best understood through its practical application in these workflows.

Explore the Markitdown MCP GitHub repository for more information.

Frequently Asked Questions

Q1. What is the main function of Markitdown MCP?

Ans. Markitdown MCP converts documents like PDFs and Word files into structured Markdown. It uses a server-based protocol for this task.

Q2. Which file formats can the Markitdown MCP server process?

Ans. The server handles PDF, DOCX, PPTX, and HTML files. Other formats may be supported depending on the core library.

Q3. How does LangChain use Markitdown MCP?

Ans. LangChain uses special tools to communicate with the server. Agents can then request document conversions through this server.

Q4. Is Markitdown MCP open source?

Ans. Yes, it is open-source software from Microsoft. Users are responsible for any server hosting costs.

Q5. Can I run the Markitdown MCP server for testing purposes?

Ans. Yes, the server for testing can run locally. Use either STDIO or SSE mode for development and evaluation.

The above is the detailed content of MarkItDown MCP Can Convert Any Document into Markdowns!. For more information, please follow other related articles on the PHP Chinese website!