Markdownify MCP 服务器

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

功能特性

• 将多种文件类型转换为 Markdown：
  • PDF
  • 图片
  • 音频（带转录）
  • DOCX
  • XLSX
  • PPTX
• 将网页内容转换为 Markdown：
  • YouTube 视频字幕
  • Bing 搜索结果
  • 通用网页
• 检索现有的 Markdown 文件

快速开始

1. 克隆此仓库
2. 安装依赖：

   pnpm install
   

注意：这也会安装 uv 及其相关的 Python 依赖。

3. 构建项目：

   pnpm run build
   

4. 启动服务器：

   pnpm start
   

开发

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

与桌面应用集成

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

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{此处填写文件的绝对路径}/dist/index.js"
      ],
      "env": {
        // 默认情况下，服务器会使用 `uv` 的默认安装路径
        "UV_PATH": "/path/to/uv"
      }
    }
  }
}

可用工具

• 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_SHARE_DIR 环境变量来限制可检索文件的目录，例如 MD_SHARE_DIR=[SOME_PATH] pnpm run start。

贡献

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

许可证

该项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

Markdownify MCP 快速上手指南

Markdownify 是一个基于模型上下文协议（MCP）的服务器，能够将 PDF、图片、音频、Office 文档及网页内容等多种格式转换为易读的 Markdown 文本。

环境准备

• 操作系统：支持 Windows、macOS 或 Linux
• 前置依赖：
  • Node.js (推荐 v18+)
  • pnpm (包管理工具)
  • Python (安装脚本会自动处理 uv 及相关 Python 依赖，无需手动配置)

国内加速建议：若安装依赖较慢，可配置 pnpm 使用国内镜像源：

pnpm config set registry https://registry.npmmirror.com

安装步骤

1. 克隆仓库

   git clone <repository-url>
   cd markdownify-mcp
   

2. 安装依赖 此步骤会自动安装 uv 及所需的 Python 库。

   pnpm install
   

3. 构建项目

   pnpm run build
   

4. 启动服务

   pnpm start
   

   可选：若需限制文件读取目录，可设置环境变量启动：

   MD_SHARE_DIR=/your/safe/path pnpm start
   

基本使用

启动成功后，该服务器可作为 MCP 客户端的工具源被调用。以下是集成到桌面应用或 AI 助手的配置示例。

1. 配置 MCP 客户端

在你的 AI 桌面应用（如 Cursor、Claude Desktop 等）的配置文件中添加以下服务器定义。请将 {ABSOLUTE PATH TO FILE HERE} 替换为你本地的实际绝对路径。

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{ABSOLUTE PATH TO FILE HERE}/dist/index.js"
      ],
      "env": {
        // 指定 uv 路径，通常可省略以使用默认安装位置
        // "UV_PATH": "/path/to/uv"
      }
    }
  }
}

2. 可用工具示例

配置完成后，你可以在对话中直接调用以下功能（具体指令取决于你的 AI 客户端）：

• 转换 YouTube 视频：youtube-to-markdown (获取视频转录文本)
• 解析本地文档：pdf-to-markdown, docx-to-markdown, pptx-to-markdown, xlsx-to-markdown
• 提取网页内容：webpage-to-markdown, bing-search-to-markdown
• 多媒体处理：image-to-markdown (含元数据), audio-to-markdown (含语音转录)
• 读取文件：get-markdown-file (读取 .md 或 .markdown 文件)

使用场景示例：

“请使用 pdf-to-markdown 工具将 /Users/name/document.pdf 转换为 Markdown 格式并总结内容。”