Markdownify MCP Server

Markdownify MCP 服务

Markdownify 是一个模型上下文协议（MCP）服务，可将各种文件类型和网页内容转换为 Markdown 格式。它提供一组工具，可将 PDF、图像、音频文件、网页等转换为易于阅读和分享的 Markdown 文本。

功能

• 将多种文件类型转换为 Markdown：
  • PDF
  • 图像
  • 音频（带转录）
  • DOCX
  • XLSX
  • PPTX
• 将网页内容转换为 Markdown：
  • YouTube 视频转录文本
  • Bing 搜索结果
  • 普通网页
• 获取现有的 Markdown 文件

开始使用

1. 克隆此代码仓库

2. 安装依赖：

   bun install
   

   preinstall 步骤会在 .venv 中创建 Python 虚拟环境，并安装 markitdown[all]。

3. 构建项目：

   bun run build
   

4. 启动服务：

   bun start
   

开发

• 使用 bun run dev 以监视模式启动 TypeScript 编译器
• 修改 src/server.ts 以自定义服务行为
• 在 src/tools.ts 中添加或修改工具

在桌面应用中使用

要将此服务集成到桌面应用中，请将以下内容添加到应用的服务配置中：

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{ABSOLUTE PATH TO FILE HERE}/dist/index.js"
      ]
    }
  }
}

环境变量

所有路径都有合理的默认值；只有在默认值不适合你的安装布局时才需要覆盖。

变量	默认值	用途
MARKITDOWN_PATH	<project>/.venv/bin/markitdown，然后是 PATH 中的 markitdown	markitdown 可执行文件的绝对路径。如果你在系统范围内安装了 markitdown（例如，使用 pipx install "markitdown[pdf]"），而不是使用捆绑的虚拟环境，请设置此项。
REPOMIX_PATH	<project>/node_modules/.bin/repomix，然后是 PATH 中的 repomix	git-repo-to-markdown 使用的 repomix 可执行文件的绝对路径。
MD_ALLOWED_PATHS	未设置（不受限制）	以路径分隔符分隔的目录列表（POSIX 系统使用 :，Windows 使用 ;），指定服务允许读取的目录。设置后，所有文件输入工具（pdf-to-markdown、get-markdown-file 等）都会拒绝访问这些目录以外的路径。
MD_SHARE_DIR	未设置	MD_ALLOWED_PATHS 的弃用别名（单个目录）。仍会为向后兼容而保留。

在 Docker 中使用

构建并运行：

docker build -t markdownify-mcp .
docker run --rm -i \
  -v "$HOME/Documents:/data:ro" \
  -e MD_ALLOWED_PATHS=/data \
  markdownify-mcp

Docker MCP 目录（mcp/markdownify）注意事项：

• 将你希望服务读取的主机目录挂载到容器中，然后向工具传递容器路径（例如 /data/foo.pdf，而不是 /Users/you/Documents/foo.pdf）。
• 将 MD_ALLOWED_PATHS 设置为以冒号分隔的已挂载目录列表，确保服务强制执行的读取边界与绑定挂载一致。
• 发布的 Docker 镜像仅安装了 markitdown[pdf]——音频转录和图像 OCR（audio-to-markdown、image-to-markdown）需要 [all] 扩展，在精简镜像中无法运行。要使用完整功能，请在本地安装（bun install）。

可用工具

• youtube-to-markdown：将 YouTube 视频转换为 Markdown

• pdf-to-markdown：将 PDF 文件转换为 Markdown

• bing-search-to-markdown：将 Bing 搜索结果转换为 Markdown

• webpage-to-markdown：将网页转换为 Markdown

• image-to-markdown：将图像转换为带元数据的 Markdown

• audio-to-markdown：将音频文件转换为带转录文本的 Markdown

• docx-to-markdown：将 DOCX 文件转换为 Markdown

• xlsx-to-markdown：将 XLSX 文件转换为 Markdown

• pptx-to-markdown：将 PPTX 文件转换为 Markdown

• get-markdown-file：获取现有的 Markdown 文件。文件扩展名必须为：.md、.markdown。

  可选：设置 MD_ALLOWED_PATHS，将所有文件输入工具限制在指定目录列表中，例如 MD_ALLOWED_PATHS=/data/in:/data/out bun start。

参与贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。