This document describes the Model Context Protocol (MCP) server implementation provided by the markitdown-mcp package. The MCP server enables AI assistants like Claude Desktop to access MarkItDown's document conversion capabilities through a standardized protocol interface.
For general Python API usage without MCP, see Python API Usage. For Docker deployment details, see Docker Environment.
The markitdown-mcp package implements an MCP server that exposes MarkItDown's conversion functionality through a single tool interface. MCP (Model Context Protocol) is a standardized protocol for connecting AI assistants to external tools and data sources.
Key Features:
convert_to_markdown(uri) for converting documents to MarkdownSources: packages/markitdown-mcp/README.md1-10 README.md7-8
The MCP server is built on the FastMCP framework and provides a bridge between MCP clients and the core MarkItDown conversion engine.
MCP Server Component Architecture
Key Code Components:
| Component | Type | Location | Description |
|---|---|---|---|
mcp | FastMCP instance | packages/markitdown-mcp/src/markitdown_mcp/__main__.py17 | Server instance with name "markitdown" |
convert_to_markdown() | Async function | packages/markitdown-mcp/src/markitdown_mcp/__main__.py20-23 | Tool decorated with @mcp.tool() |
check_plugins_enabled() | Function | packages/markitdown-mcp/src/markitdown_mcp/__main__.py26-31 | Reads MARKITDOWN_ENABLE_PLUGINS env var |
create_starlette_app() | Function | packages/markitdown-mcp/src/markitdown_mcp/__main__.py34-78 | Constructs Starlette app for HTTP/SSE |
main() | Function | packages/markitdown-mcp/src/markitdown_mcp/__main__.py82-124 | CLI entry point with argument parsing |
SseServerTransport | Class | packages/markitdown-mcp/src/markitdown_mcp/__main__.py35 | SSE transport at /messages/ |
StreamableHTTPSessionManager | Class | packages/markitdown-mcp/src/markitdown_mcp/__main__.py36-41 | HTTP session manager for /mcp |
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py1-128 packages/markitdown-mcp/README.md7-10
The MCP server supports three transport mechanisms implemented through different code paths in __main__.py.
Transport Mode Execution Flow
STDIO is the default transport mode using standard input/output streams.
Characteristics:
args.http and args.sse are both Falsemcp.run() call at packages/markitdown-mcp/src/markitdown_mcp/__main__.py123Code Path:
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py107-123 packages/markitdown-mcp/README.md20-26
Streamable HTTP enables RESTful HTTP communication with the MCP server.
Characteristics:
/mcp via Mount("/mcp", app=handle_streamable_http) packages/markitdown-mcp/src/markitdown_mcp/__main__.py74StreamableHTTPSessionManager with json_response=True and stateless=True packages/markitdown-mcp/src/markitdown_mcp/__main__.py36-41host="127.0.0.1", port=3001 packages/markitdown-mcp/src/markitdown_mcp/__main__.py119-120uvicorn.run(starlette_app, ...) packages/markitdown-mcp/src/markitdown_mcp/__main__.py117-121Configuration:
Handler Implementation:
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py34-78 packages/markitdown-mcp/src/markitdown_mcp/__main__.py115-121 packages/markitdown-mcp/README.md28-32
Server-Sent Events (SSE) provides a unidirectional event stream from server to client.
Characteristics:
/sse via Route("/sse", endpoint=handle_sse) packages/markitdown-mcp/src/markitdown_mcp/__main__.py73/messages/ via Mount("/messages/", app=sse.handle_post_message) packages/markitdown-mcp/src/markitdown_mcp/__main__.py75SseServerTransport("/messages/") packages/markitdown-mcp/src/markitdown_mcp/__main__.py35sse.connect_sse() context manager packages/markitdown-mcp/src/markitdown_mcp/__main__.py44-48Configuration: Same as HTTP mode (--http flag)
Handler Implementation:
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py34-78 packages/markitdown-mcp/src/markitdown_mcp/__main__.py43-53 packages/markitdown-mcp/README.md117-120
The MCP server exposes a single tool that wraps MarkItDown's conversion functionality.
Tool Specification:
| Property | Value |
|---|---|
| Name | convert_to_markdown |
| Input Parameter | uri: str - Resource URI to convert |
| Supported URI Schemes | http:, https:, file:, data: |
| Return Type | str - Markdown text content |
| Async | Yes |
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py20-23 packages/markitdown-mcp/README.md9
The tool respects the MARKITDOWN_ENABLE_PLUGINS environment variable to control plugin loading.
Environment Variable Values:
| Value | Plugin Behavior |
|---|---|
"true", "1", "yes" | Plugins enabled |
| Any other value or unset | Plugins disabled |
Implementation: packages/markitdown-mcp/src/markitdown_mcp/__main__.py26-31
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py26-31
convert_to_markdown() Invocation Sequence
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py20-31
The MCP server is distributed as a separate package from the core MarkItDown library.
Installation via pip:
Installation from source:
After installation, the markitdown-mcp command becomes available in the environment.
Sources: packages/markitdown-mcp/README.md11-17
The server can be run in multiple configurations depending on the desired transport mode.
Command:
This starts the server listening on stdin/stdout, suitable for local process invocation.
Sources: packages/markitdown-mcp/README.md20-26
Command:
Command-Line Arguments:
| Argument | Default | Description |
|---|---|---|
--http | False | Enable HTTP and SSE transports |
--sse | False | Deprecated alias for --http |
--host | 127.0.0.1 | Host address to bind (HTTP mode only) |
--port | 3001 | Port to listen on (HTTP mode only) |
Validation: The server rejects --host and --port arguments in STDIO mode packages/markitdown-mcp/src/markitdown_mcp/__main__.py109-113
Sources: packages/markitdown-mcp/src/markitdown_mcp/__main__.py82-124 packages/markitdown-mcp/README.md28-32
Build Image:
Run Container (STDIO):
Run with Volume Mount:
File Access: Files from the host's /home/user/data directory are accessible at /workdir inside the container. For example, /home/user/data/example.txt becomes file:///workdir/example.txt.
Sources: packages/markitdown-mcp/README.md34-51
Claude Desktop can use the MCP server to access MarkItDown conversion capabilities through its MCP client interface.
1. Locate Configuration File:
Follow the MCP quickstart instructions to find claude_desktop_config.json.
2. Add Server Configuration:
Basic Docker Configuration:
Configuration with Volume Mount:
Configuration Properties:
| Property | Description |
|---|---|
mcpServers | Root object for MCP server definitions |
markitdown | Server identifier (arbitrary name) |
command | Executable to run (docker for containerized deployment) |
args | Command-line arguments array |
Sources: packages/markitdown-mcp/README.md53-95
Once configured, Claude Desktop:
convert_to_markdown toolThe integration is transparent to users; Claude decides when to use the tool based on conversation context.
Sources: packages/markitdown-mcp/README.md53-57
The MCP Inspector provides a web-based interface for testing and debugging the MCP server.
Command:
This launches a web interface, typically at http://localhost:5173/.
Sources: packages/markitdown-mcp/README.md97-105
Configuration Steps:
STDIO as transport typemarkitdown-mcp as the commandConnectSources: packages/markitdown-mcp/README.md107-110
Configuration Steps:
Streamable HTTP as transport typehttp://127.0.0.1:3001/mcp as URLConnectPrerequisite: Server must be running with --http flag.
Sources: packages/markitdown-mcp/README.md112-115
Configuration Steps:
SSE as transport typehttp://127.0.0.1:3001/sse as URLConnectPrerequisite: Server must be running with --http flag.
Sources: packages/markitdown-mcp/README.md117-120
After Connection:
Tools tabList Tools to discover available toolsconvert_to_markdownhttp://example.com, file:///path/to/file.pdf)The inspector displays the tool's output (Markdown text) and any errors.
Sources: packages/markitdown-mcp/README.md122-126
The MCP server implementation has important security characteristics that users must understand.
Current State: The server does not implement authentication mechanisms.
Implications:
Sources: packages/markitdown-mcp/README.md128-130
Execution Context: The server runs with the privileges of the user who started it.
Implications:
Sources: packages/markitdown-mcp/README.md128-130
Recommendation: When using HTTP or SSE transport, bind to localhost (default behavior).
Default Configuration:
Risk of External Binding: Binding to 0.0.0.0 or a public IP address exposes the server to network access without authentication.
Sources: packages/markitdown-mcp/README.md128-130 packages/markitdown-mcp/src/markitdown_mcp/__main__.py100-104
Benefit: Running in Docker provides process isolation and filesystem sandboxing.
Volume Mount Security: When mounting host directories into containers, only mount directories that the server needs access to, using read-only mounts where possible:
Refresh this wiki