Markdownify MCP Server for Claude Code: Setup & Config

What you can do with Markdownify in Claude Code

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

• Convert PDF and office documents into assistant-readable Markdown.
• Read existing Markdown within an explicitly allowed directory set.

Before you start: Markdownify in Claude Code

• 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 Claude Code configuration

1. Choose Claude Code configuration scope

   For Markdownify MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Markdownify MCP Server to Claude Code

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

3. Check Markdownify MCP Server in Claude Code

   Markdownify MCP Server: Inspect claude mcp list and /mcp status.

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

claude mcp add-json --scope project 'markdownify-mcp' '{"type":"stdio","command":"bun","args":["start"],"env":{"MD_ALLOWED_PATHS":"<allowed directories separated by your platform path delimiter>"}}'

Markdownify tools available to Claude Code

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

youtube-to-markdown

For Markdownify's youtube-to-markdown, review the permission request and arguments in Claude Code before approval.

pdf-to-markdown

For Markdownify's pdf-to-markdown, review the permission request and arguments in Claude Code before approval.

bing-search-to-markdown

For Markdownify's bing-search-to-markdown, review the permission request and arguments in Claude Code before approval.

Represent Bing search results as Markdown.

webpage-to-markdown

For Markdownify's webpage-to-markdown, review the permission request and arguments in Claude Code before approval.

Extract web page content into Markdown.

image-to-markdown

For Markdownify's image-to-markdown, review the permission request and arguments in Claude Code before approval.

Produce Markdown from an image with associated metadata.

audio-to-markdown

For Markdownify's audio-to-markdown, review the permission request and arguments in Claude Code before approval.

docx-to-markdown

For Markdownify's docx-to-markdown, review the permission request and arguments in Claude Code before approval.

Transform a DOCX document into Markdown.

xlsx-to-markdown

For Markdownify's xlsx-to-markdown, review the permission request and arguments in Claude Code before approval.

pptx-to-markdown

For Markdownify's pptx-to-markdown, review the permission request and arguments in Claude Code before approval.

get-markdown-file

For Markdownify's get-markdown-file, review the permission request and arguments in Claude Code before approval.

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

git-repo-to-markdown

For Markdownify's git-repo-to-markdown, review the permission request and arguments in Claude Code before approval.

Convert repository content using the configured Repomix executable.

Markdownify: full stored tool descriptions

Troubleshooting Markdownify in Claude Code

• If Markdownify MCP Server fails to start, check bun, the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Markdownify MCP Server: check MD_ALLOWED_PATHS; keep credentials out of shared .mcp.json.
• Markdownify MCP Server uses stdio here: Claude Code 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 Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions