Server facts
Markdownify MCP Server
Project
- Author
- zcaceres
- Repository
- github.com/zcaceres/markdownify-mcp
- License
- MIT
- Category
- Files & Documents
Tech
- Runtime / language
- nodeTypeScript
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 2,997
- Last commit
- Data as of
Tags
- Audio Transcription
- Document Conversion
- Markdown
- Web Extraction
Overview
Markdownify MCP Server turns several kinds of files and online content into Markdown for assistant workflows. Document inputs include PDF, DOCX, XLSX, and PPTX, while media tools cover images and audio transcription. Web-facing tools work with ordinary pages, Bing search results, and YouTube video transcripts. A retrieval tool also reads existing Markdown files. This gives users a common textual format when gathering material from sources that would otherwise require different readers or conversion steps.
The local setup uses Bun to install dependencies and build the TypeScript project. During installation, a Python virtual environment is created for the MarkItDown conversion dependency with its full extras. Desktop-client configuration can then launch the built JavaScript entry point through Node. Docker operation is documented as an alternative, with read-only directory mounts shown in the example. File-access boundaries deserve attention: without an allowlist, file-input tools are unrestricted. Setting MD_ALLOWED_PATHS restricts reads to specified directories, and container users must pass paths inside the container rather than host filesystem paths. The README also distinguishes the published slim Docker image from the full local installation. That image installs only the PDF extras, so audio transcription and image OCR will fail there unless the required extras are available. Choosing an installation path therefore affects which advertised conversions can actually run.
Install & configure
Requirements
- Bun
- A cloned repository with dependencies installed and the project built
- Python for the MarkItDown environment created during installation
bun startRun 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.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"markdownify-mcp": {
"command": "bun",
"args": [
"start"
],
"env": {
"MD_ALLOWED_PATHS": "<allowed directories separated by your platform path delimiter>"
}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"markdownify-mcp": {
"command": "bun",
"args": [
"start"
],
"env": {
"MD_ALLOWED_PATHS": "<allowed directories separated by your platform path delimiter>"
}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"markdownify-mcp": {
"type": "stdio",
"command": "bun",
"args": [
"start"
],
"env": {
"MD_ALLOWED_PATHS": "<allowed directories separated by your platform path delimiter>"
}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"markdownify-mcp": {
"command": "bun",
"args": [
"start"
],
"env": {
"MD_ALLOWED_PATHS": "<allowed directories separated by your platform path delimiter>"
}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"markdownify-mcp": {
"type": "stdio",
"command": "bun",
"args": [
"start"
],
"env": {
"MD_ALLOWED_PATHS": "<allowed directories separated by your platform path delimiter>"
}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| youtube-to-markdown | Extract a YouTube video's transcript into Markdown. |
| pdf-to-markdown | Transform PDF content into Markdown text. |
| bing-search-to-markdown | Represent Bing search results as Markdown. |
| webpage-to-markdown | Extract web page content into Markdown. |
| image-to-markdown | Produce Markdown from an image with associated metadata. |
| audio-to-markdown | Transcribe audio and present the result as Markdown. |
| docx-to-markdown | Transform a DOCX document into Markdown. |
| xlsx-to-markdown | Represent spreadsheet content from XLSX as Markdown. |
| pptx-to-markdown | Transform presentation content from PPTX into Markdown. |
| get-markdown-file | Read an existing file with a .md or .markdown extension. |
| git-repo-to-markdown | Convert repository content using the configured Repomix executable. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Convert PDF and office documents into assistant-readable Markdown.
- Extract web pages or YouTube transcripts for text-based review.
- Transcribe audio as part of a document conversion workflow.
- Read existing Markdown within an explicitly allowed directory set.
Strengths
- Covers document, media, and web sources with one output format.
- Provides configurable directory restrictions for file-input tools.
- Documents both a full local setup and container operation.
Limitations
- File access is unrestricted unless allowed directories are configured.
- The published slim Docker image lacks audio transcription and image OCR extras.
- The full local installation involves JavaScript tooling and a Python conversion environment.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
