markdown-notes-mcp

---

**许可证：**可免费用于个人非商业用途。请参阅 LICENSE.md。

功能介绍

AI 助手可以读取纯文本，有些还可以读取 PDF。但它们都无法读取 EPUB、OpenDocument、PowerPoint 或扫描图像，而且都会先将文件上传到服务 器。

此工具会在你自己的设备上转换文档，并返回经过整理、便于大模型阅读的 Markdown——将表格转换为真正的 Markdown 表格、简化深层缩进，并正确标记代码块。

文档	PDF、Word .docx、Excel .xlsx/.xls/.xlsm、PowerPoint .pptx、OpenDocument .odt/.ods、EPUB、CSV、TSV、纯文本
图像	在设备上进行 OCR，无需密钥，也无需联网
音频	转录——这是唯一无法在本地运行的功能

工具

工具	功能
convert_to_markdown	转换单个文件，并自动将 .md 文件保存在原文件旁边
convert_folder_to_markdown	将多个文件转换到指定目录
save_summary	将助手撰写的摘要以 <name>.summary.md 的形式保存在文档旁边
list_supported_formats	列出支持的扩展名，以及已配置的可选云端功能

关于令牌

转换不会产生任何费用——所有操作都在本地完成。但将长文档返回到对话中确实会消耗令牌，费率与手动粘贴相同。

因此，较长的转换结果会保存到磁盘，只返回简短预览。50 页的 PDF 大约消耗 400 个令牌，而不是 30,000 个。短文档会完整返回，因为无论如何消耗都很少。使用 return_content: "full" 可覆盖此行为。

安装

Claude Desktop — 简便方式

从 Releases 下载 .mcpb 文件，然后双击。Claude Desktop 会安装它，并询问允许读取哪些文件夹，以及是否提供 API 密钥。无需 Node、终端或 JSON。

Claude Desktop — 从源码安装

npm install
npm run build
node scripts/install-claude-desktop.mjs --roots "D:\your\documents"

然后彻底重启 Claude Desktop。该脚本会修改现有配置，而不是替换配置，并会先写入带时间戳的备份。

--roots 为可选参数，但建议使用：它会限制 MCP 服务可以读取的文件夹。不使用时，助手请求的任何路径都允许访问。

如需移除：node scripts/install-claude-desktop.mjs --remove

从 npm 安装 — 适用于任何 MCP 宿主

npm install -g suprasuta-markdown-mcp

然后将宿主指向 suprasuta-markdown-mcp 命令，或直接运行而不安装：

{
  "servers": {
    "suprasuta-markdown": {
      "command": "npx",
      "args": ["-y", "suprasuta-markdown-mcp"],
      "env": { "MARKDOWN_MCP_ROOTS": "D:\\your\\documents" }
    }
  }
}

VS Code 和 Antigravity

两者都读取标准 MCP 配置——上方的配置块可直接使用。 Antigravity 会读取 ~/.gemini/config/mcp_config.json，或工作区内的 .agents/mcp_config.json。

如果要运行本地检出版本，而不是已发布的软件包，请将 command 和 args 替换为 node 和 dist/server.js 的绝对路径。

可选云端功能

只有提供密钥后，这两项功能才会启用。其他所有功能无需密钥即可使用。

变量	启用的功能	离开你设备的内容
GEMINI_API_KEY	云端 OCR，也可描述图表和示意图	图像会发送给 Google
ASSEMBLYAI_API_KEY	音频转录	音频文件会发送给 AssemblyAI

密钥从环境变量中读取，绝不会写入磁盘或记录到日志中。

设置只会在启动时读取一次。 MCP 服务是长期运行的进程，因此在运行期间保存的密钥或文件夹设置，只有宿主重启后才会生效。如果刚输入的密钥显示为未配置，请先重启宿主，再排查其他问题。

开发

npm install          # .npmrc sets include=dev — do not delete it
npm run build        # stages the OCR engine, then bundles with esbuild
npm test             # 19 tests against the built bundle
npm run smoke        # converts every file in samples/ and reports
npm run typecheck

为什么构建使用 esbuild 而不是 tsc

src/lib/convert/ 与 Windows、Web 和 Android 应用中的副本保持字节级一致，这样就能及时发现差异，而不是等到问题暴露后才发现。这些文件使用了无扩展名导入和一个 Vite 专用的 ?url 导入，而 Node 自带的解析器都无法处理。esbuild 可以解析这两者，因此共享文件无需为适配 Node 而修改。

运行时钩子

浏览器和 Node 之间确实有三处差异，src/lib/convert/runtime.ts 会询问宿主环境，而不是通过检查 process 来判断：

钩子	原因
tesseractPaths	浏览器需要 URL 和自己的工作线程；Node 需要文件系统路径，且绝不能传入浏览器工作线程
docxSource	mammoth 在浏览器中读取 arrayBuffer，在 Node 中读取 buffer
ocrImageInput	tesseract 的 Node 构建无法解码 Blob；它需要 Buffer

其他部分都是共享的。src/runtime/node.ts 提供 Node 所需的值，并且只对一个浏览器全局对象 DOMParser 提供垫片。

一个惨痛教训：该文件以前也定义了 document，结果导致 OCR 出错。tesseract.js 检测到 DOM 后走了浏览器分支，最终因 window is not defined 而崩溃。半套浏览器环境比没有更糟——只提供最低限度的垫片。

确保副本保持一致

npm run sync:check              # list differences against all three apps
npm run sync:pull web           # bring the web app's version in
node scripts/sync-converters.mjs --push web

此软件包是规范副本：它是唯一包含运行时钩子的副本，能让相同文件在两种环境中运行，因此修复从这里开始，再向外同步。sync:check 会报告差异并以零状态码退出——差异是信息，不是构建失败。

隐私政策

本软件不会收集任何信息。没有账户、分析、遥测，也没有自有服务器——文档转换完全在你的设备上进行。

两项可选功能会向第三方发送数据，且仅在你提供自己的 API 密钥时才会发送：云端图像识别会将图像发送给 Google，音频转录会将音频发送给 AssemblyAI。未配置密钥时，软件不会建立任何网络连接。API 密钥从环境中读取，不会写入磁盘，也不会记录到日志中。

完整政策涵盖数据收集、存储、保留、与第三方共享及联系方式：PRIVACY.md。

相关项目

Windows 应用	Microsoft Store · 源代码
Web 应用	markdown-notes-psi.vercel.app · 源代码
Android	通过 Chrome 安装 Web 应用 · 较早的原生版本，已不再维护