MCP Directory

How to add Markdownify MCP to Windsurf

Convert PDFs, Office docs, images, audio, and web pages into Markdown for LLM consumption. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 2.6k★ · stdio · no auth

Windsurf config for Markdownify MCP

git clone https://github.com/zcaceres/markdownify-mcp && cd markdownify-mcp && pnpm install && pnpm run build
{
  "mcpServers": {
    "markdownify-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/markdownify-mcp/dist/index.js"
      ]
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Markdownify MCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Markdownify MCP's tools become available to Cascade.

Before you start

  • Node.js with a JavaScript runtime/package manager — the repo uses Bun (bun install / bun run build / bun start)
  • Python 3 available on the system — the install step creates a .venv and installs markitdown[all] (audio/image conversion may need additional system tools like ffmpeg/exiftool depending on input)
  • No API keys or credentials required for local file conversion; web/search tools fetch public URLs

What Markdownify MCP can do in Windsurf

pdf-to-markdown

Convert a PDF file to Markdown.

docx-to-markdown

Convert a Word .docx file to Markdown.

xlsx-to-markdown

Convert an Excel .xlsx file to Markdown.

pptx-to-markdown

Convert a PowerPoint .pptx file to Markdown.

image-to-markdown

Extract text from an image (OCR) and return Markdown.

audio-to-markdown

Transcribe an audio file and return Markdown.

webpage-to-markdown

Fetch a web page and convert it to Markdown.

youtube-to-markdown

Fetch a YouTube video's transcript as Markdown.

Security

It reads local files and fetches remote URLs you point it at, and transcription/conversion may invoke bundled Python tooling; run it only on documents you trust. Build-from-source means you should review the repo before running.

Markdownify MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Markdownify MCP config there under the "mcpServers" key and restart the client.

Is Markdownify MCP safe to use with Windsurf?

It reads local files and fetches remote URLs you point it at, and transcription/conversion may invoke bundled Python tooling; run it only on documents you trust. Build-from-source means you should review the repo before running.

Is this an official Microsoft/markitdown server?

No. It's a community project by Zach Caceres that wraps Microsoft's markitdown engine; it is MIT-licensed but not vendored by Microsoft.

Do I need Python even though it's a Node server?

Yes. The TypeScript server shells out to markitdown, which is Python; the install step provisions a .venv with markitdown[all]. You can override the binary path with MARKITDOWN_PATH.

Does it require any API keys?

No. Local file conversions and the web/YouTube/Bing tools work without credentials; the web tools simply fetch public URLs.

View repo Full Markdownify MCP page