Markdownify MCP Server for Windsurf: Setup & Config

What you can do with Markdownify in Windsurf

Unify mixed documents and web material as Markdown, with explicit directory read boundaries.

• Extract web pages or YouTube transcripts for text-based review.
• Read existing Markdown within an explicitly allowed directory set.

Before you start: Markdownify in Windsurf

• Bun
• A cloned repository with dependencies installed and the project built
• Python for the MarkItDown environment created during installation

Run bun install and bun run build first. The local installation uses markitdown[all]. Set allowed paths to restrict file reads; the slim published Docker image lacks audio and image extras.

Markdownify Windsurf configuration

1. Choose Windsurf configuration scope

   For Markdownify MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Markdownify MCP Server to Windsurf

   Use the markdownify-mcp entry below in mcpServers. Keep Markdownify MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Markdownify MCP Server in Windsurf

   Markdownify MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "markdownify-mcp": {
      "command": "bun",
      "args": [
        "start"
      ],
      "env": {
        "MD_ALLOWED_PATHS": "<allowed directories separated by your platform path delimiter>"
      }
    }
  }
}

Markdownify tools available to Windsurf

Markdownify's stored tool list documents 11 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

youtube-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for youtube-to-markdown.

Extract a YouTube video's transcript into Markdown.

pdf-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for pdf-to-markdown.

Transform PDF content into Markdown text.

bing-search-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for bing-search-to-markdown.

webpage-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for webpage-to-markdown.

image-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for image-to-markdown.

Produce Markdown from an image with associated metadata.

audio-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for audio-to-markdown.

Transcribe audio and present the result as Markdown.

docx-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for docx-to-markdown.

xlsx-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for xlsx-to-markdown.

pptx-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for pptx-to-markdown.

get-markdown-file

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for get-markdown-file.

Read an existing file with a .md or .markdown extension.

git-repo-to-markdown

After refreshing Markdownify in Windsurf settings, check Cascade's tool list for git-repo-to-markdown.

Convert repository content using the configured Repomix executable.

Markdownify: full stored tool descriptions

Troubleshooting Markdownify in Windsurf

• Check bun on the machine running Windsurf's MCP integration for Markdownify MCP Server; refresh MCP and inspect Cascade's tools.
• Check MD_ALLOWED_PATHS for Markdownify MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Markdownify MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: File access is unrestricted unless allowed directories are configured.
• Known limitation: The published slim Docker image lacks audio transcription and image OCR extras.
• Known limitation: The full local installation involves JavaScript tooling and a Python conversion environment.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions