Markitdown MCP

1# MarkItDown-MCP
2 
3[![PyPI](https://img.shields.io/pypi/v/markitdown-mcp.svg)](https://pypi.org/project/markitdown-mcp/)
4![PyPI - Downloads](https://img.shields.io/pypi/dd/markitdown-mcp)
5[![Built by AutoGen Team](https://img.shields.io/badge/Built%20by-AutoGen%20Team-blue)](https://github.com/microsoft/autogen)
6 
7The `markitdown-mcp` package provides a lightweight STDIO, Streamable HTTP, and SSE MCP server for calling MarkItDown.
8 
9It exposes one tool: `convert_to_markdown(uri)`, where uri can be any `http:`, `https:`, `file:`, or `data:` URI.
10 
11## Installation
12 
13To install the package, use pip:
14 
15```bash
16pip install markitdown-mcp
17```
18 
19## Usage
20 
21To run the MCP server, using STDIO (default) use the following command:
22 
23 
24```bash	
25markitdown-mcp
26```
27 
28To run the MCP server, using Streamable HTTP and SSE use the following command:
29 
30```bash	
31markitdown-mcp --http --host 127.0.0.1 --port 3001
32```
33 
34## Running in Docker
35 
36To run `markitdown-mcp` in Docker, build the Docker image using the provided Dockerfile:
37```bash
38docker build -t markitdown-mcp:latest .
39```
40 
41And run it using:
42```bash
43docker run -it --rm markitdown-mcp:latest
44```
45This will be sufficient for remote URIs. To access local files, you need to mount the local directory into the container. For example, if you want to access files in `/home/user/data`, you can run:
46 
47```bash
48docker run -it --rm -v /home/user/data:/workdir markitdown-mcp:latest
49```
50 
51Once mounted, all files under data will be accessible under `/workdir` in the container. For example, if you have a file `example.txt` in `/home/user/data`, it will be accessible in the container at `/workdir/example.txt`.
52 
53## Accessing from Claude Desktop
54 
55It is recommended to use the Docker image when running the MCP server for Claude Desktop.
56 
57Follow [these instructions](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users) to access Claude's `claude_desktop_config.json` file.
58 
59Edit it to include the following JSON entry:
60 
61```json
62{
63  "mcpServers": {
64    "markitdown": {
65      "command": "docker",
66      "args": [
67        "run",
68        "--rm",
69        "-i",
70        "markitdown-mcp:latest"
71      ]
72    }
73  }
74}
75```
76 
77If you want to mount a directory, adjust it accordingly:
78 
79```json
80{
81  "mcpServers": {
82    "markitdown": {
83      "command": "docker",
84      "args": [
85	"run",
86	"--rm",
87	"-i",
88	"-v",
89	"/home/user/data:/workdir",
90	"markitdown-mcp:latest"
91      ]
92    }
93  }
94}
95```
96 
97## Debugging
98 
99To debug the MCP server you can use the `mcpinspector` tool.
100 
101```bash
102npx @modelcontextprotocol/inspector
103```
104 
105You can then connect to the inspector through the specified host and port (e.g., `http://localhost:5173/`).
106 
107If using STDIO:
108* select `STDIO` as the transport type,
109* input `markitdown-mcp` as the command, and
110* click `Connect`
111 
112If using Streamable HTTP:
113* select `Streamable HTTP` as the transport type,
114* input `http://127.0.0.1:3001/mcp` as the URL, and
115* click `Connect`
116 
117If using SSE:
118* select `SSE` as the transport type,
119* input `http://127.0.0.1:3001/sse` as the URL, and
120* click `Connect`
121 
122Finally:
123* click the `Tools` tab,
124* click `List Tools`,
125* click `convert_to_markdown`, and
126* run the tool on any valid URI.
127 
128## Security Considerations
129 
130The server does not support authentication, and runs with the privileges of the user running it. For this reason, when running in SSE or Streamable HTTP mode, it is recommended to run the server bound to `localhost` (default).
131 
132## Trademarks
133 
134This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
135trademarks or logos is subject to and must follow
136[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
137Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
138Any use of third-party trademarks or logos are subject to those third-party's policies.
139