How to add MarkItDown MCP to Windsurf
Give your agent Microsoft's MarkItDown: convert PDFs, Office docs, images, and URLs into LLM-ready Markdown. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.
Last updated June 14, 2026 · 162k★ · stdio · no auth · official
Windsurf config for MarkItDown MCP
pip install markitdown-mcp{
"mcpServers": {
"markitdown-mcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"markitdown-mcp:latest"
]
}
}
}Requires Docker to be installed and running.
Setup steps
- 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
- 2Paste the MarkItDown MCP config below.
- 3Fill in placeholder secrets, then save.
- 4Click Refresh in the MCP panel.
- 5MarkItDown MCP's tools become available to Cascade.
Before you start
- Python 3.10+ and pip (pip install markitdown-mcp), or Docker for the containerized setup
- For the recommended Claude Desktop config: build the image first with `docker build -t markitdown-mcp:latest .` from packages/markitdown-mcp
- No API keys or accounts required
What MarkItDown MCP can do in Windsurf
convert_to_markdownConvert any http:, https:, file:, or data: URI to Markdown.
Security
No authentication: the server runs with your user's privileges, and convert_to_markdown can read any file or network resource that user can reach. Keep it on STDIO or bound to localhost (the default) and use the Docker container with a mounted workdir when you want isolation.
MarkItDown MCP + Windsurf FAQ
Where is the Windsurf config file?
Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the MarkItDown MCP config there under the "mcpServers" key and restart the client.
Is MarkItDown MCP safe to use with Windsurf?
No authentication: the server runs with your user's privileges, and convert_to_markdown can read any file or network resource that user can reach. Keep it on STDIO or bound to localhost (the default) and use the Docker container with a mounted workdir when you want isolation.
Is MarkItDown-MCP safe to run?
Safe for local, single-user use — but it has no authentication, and convert_to_markdown can read any file or network resource your user can. Microsoft's README explicitly warns to keep it bound to localhost (the default) and suggests a container or VM if you need stronger isolation.
What file types can it convert?
Everything MarkItDown supports: PDF, Word, PowerPoint, Excel, images (EXIF/OCR), audio (transcription), HTML, CSV/JSON/XML, ZIP archives, YouTube URLs, EPUBs and more. The tool takes a URI, so both local files (file:) and remote pages (http/https) work.
Do I need to install markitdown separately?
No. `pip install markitdown-mcp` pulls MarkItDown in as a dependency — the MCP package is just a thin STDIO/HTTP/SSE server exposing the one conversion tool.