Skip to main content
The MarkItDown MCP server supports three transport modes: STDIO, Streamable HTTP, and SSE (Server-Sent Events). Each mode is suited for different integration scenarios.

​
Server Modes

​
STDIO Mode (Default)

STDIO mode uses standard input and output for communication. This is the default mode and is ideal for local desktop applications like Claude Desktop. 
markitdown-mcp
The server will start and wait for MCP protocol messages on stdin, writing responses to stdout. Use cases:
  • Claude Desktop integration
  • Local AI assistant applications
  • Process-based integration

​
Streamable HTTP Mode

Streamable HTTP mode runs a web server that handles MCP requests over HTTP. Start the server with the --http flag: 
markitdown-mcp --http --host 127.0.0.1 --port 3001
Command-line options:
OptionDefaultDescription
--httpfalseEnable HTTP and SSE transport modes
--host127.0.0.1Host address to bind to
--port3001Port number to listen on
The server exposes two endpoints:
  • /mcp - Streamable HTTP transport endpoint
  • /sse - Server-Sent Events endpoint
Use cases:
  • Web-based AI applications
  • Remote MCP client access
  • Microservice architectures

​
SSE Mode

SSE (Server-Sent Events) mode is included when using the --http flag. The SSE endpoint is available at /sse. 
markitdown-mcp --http --host 127.0.0.1 --port 3001
Clients can connect to http://127.0.0.1:3001/sse for event-based communication. Use cases:
  • Real-time streaming applications
  • Browser-based clients
  • Event-driven architectures

​
The convert_to_markdown Tool

The MCP server exposes a single tool: convert_to_markdown.

​
Tool Signature

convert_to_markdown(uri: str) -> str

​
Parameters

  • uri (string, required): A URI pointing to the resource to convert

​
Supported URI Schemes

SchemeDescriptionExample
http:HTTP URLhttp://example.com/doc.pdf
https:HTTPS URLhttps://example.com/doc.docx
file:Local file pathfile:///home/user/document.pdf
data:Inline datadata:text/html;base64,PGh0bWw+...

​
Return Value

The tool returns a string containing the Markdown representation of the document.

​
Example Usage

When using the tool through an MCP client (like Claude Desktop or mcpinspector): 
{
  "uri": "https://example.com/document.pdf"
}
The tool will:
  1. Download or read the resource from the URI
  2. Detect the file type automatically
  3. Convert the content to Markdown
  4. Return the Markdown text

​
Running with Docker

​
Basic Docker Usage

For remote URIs (http/https), run the container with basic options: 
docker run -it --rm markitdown-mcp:latest

​
Accessing Local Files

To convert local files, mount a directory into the container: 
docker run -it --rm -v /home/user/data:/workdir markitdown-mcp:latest
Files in /home/user/data will be accessible at /workdir in the container. Example: If you have /home/user/data/example.txt, use the URI: 
file:///workdir/example.txt

​
Running in HTTP Mode

Run the Docker container in HTTP mode: 
docker run -it --rm -p 3001:3001 markitdown-mcp:latest --http --host 0.0.0.0 --port 3001
When running in HTTP or SSE mode, the server does not support authentication. Always bind to localhost (127.0.0.1) unless running in a trusted network.

​
Debugging with mcpinspector

The MCP Inspector is a tool for testing and debugging MCP servers.

​
Starting the Inspector

Run the inspector: 
px @modelcontextprotocol/inspector
Open the inspector in your browser at http://localhost:5173/.

​
Connecting to STDIO Server

  1. Select STDIO as the transport type
  2. Enter markitdown-mcp as the command
  3. Click Connect

​
Connecting to Streamable HTTP Server

  1. Start the MCP server in HTTP mode: 
    markitdown-mcp --http --host 127.0.0.1 --port 3001
  2. In the inspector:
    • Select Streamable HTTP as the transport type
    • Enter http://127.0.0.1:3001/mcp as the URL
    • Click Connect

​
Connecting to SSE Server

  1. Start the MCP server in HTTP mode (same command as above)
  2. In the inspector:
    • Select SSE as the transport type
    • Enter http://127.0.0.1:3001/sse as the URL
    • Click Connect

​
Testing the Tool

Once connected:
  1. Click the Tools tab
  2. Click List Tools to see available tools
  3. Click convert_to_markdown
  4. Enter a URI in the parameters (e.g., https://example.com/test.pdf)
  5. Click Run to execute the tool
The inspector will display the Markdown output.

​
Security Considerations

The MCP server runs with the privileges of the user executing it and does not implement authentication.

​
Best Practices

  1. Bind to localhost: When running in HTTP/SSE mode, always bind to 127.0.0.1 (the default) to prevent external access
  2. Use Docker for isolation: Run the server in Docker to limit file system access
  3. Mount only necessary directories: When using Docker, only mount directories that need to be accessed
  4. Be cautious with file:// URIs: The server can access any file readable by the user running it
  5. Validate URIs: When integrating the server into applications, validate and sanitize URIs before passing them to the tool
  6. Network access: Consider using firewall rules to restrict access to the server when running in HTTP/SSE mode

​
Next Steps

Claude Desktop Integration

Set up Claude Desktop to use the MCP server

API Reference

Explore MarkItDown’s Python API

Build docs developers (and LLMs) love

Get started for freeTalk to us