> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/markitdown/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage Guide
> Learn how to run the MarkItDown MCP server in different modes
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.
```bash theme={null}
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:
```bash theme={null}
markitdown-mcp --http --host 127.0.0.1 --port 3001
```
**Command-line options:**
| Option | Default | Description |
| -------- | --------- | ----------------------------------- |
| `--http` | false | Enable HTTP and SSE transport modes |
| `--host` | 127.0.0.1 | Host address to bind to |
| `--port` | 3001 | Port 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`.
```bash theme={null}
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
```python theme={null}
convert_to_markdown(uri: str) -> str
```
### Parameters
* `uri` (string, required): A URI pointing to the resource to convert
### Supported URI Schemes
| Scheme | Description | Example |
| -------- | --------------- | ----------------------------------- |
| `http:` | HTTP URL | `http://example.com/doc.pdf` |
| `https:` | HTTPS URL | `https://example.com/doc.docx` |
| `file:` | Local file path | `file:///home/user/document.pdf` |
| `data:` | Inline data | `data: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):
```json theme={null}
{
"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:
```bash theme={null}
docker run -it --rm markitdown-mcp:latest
```
### Accessing Local Files
To convert local files, mount a directory into the container:
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
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
Set up Claude Desktop to use the MCP server
Explore MarkItDown's Python API