distill-mcp

distill-mcp

一个 MCP 服务，可将任何兼容 MCP 的客户端连接到 Distill，在大模型读取本地文档前，将其转换为简洁且节省 Token 的 Markdown。 与原始文档文本相比，通常可减少 40–80% 的 Token，让模型的上下文窗口容纳更多内容，并更快地进行推理。

支持 Claude Desktop、Claude Code、Cursor、Windsurf，以及任何支持工具调用的其他 MCP 客户端。

两种模式

	轻量模式	完整模式（Docker）
是否需要 Docker	否	是
DOCX、XLSX、PPTX、原生 PDF、HTML	是	是
扫描版 PDF（OCR）	否	是
音频（MP3、WAV 等）	否	是
质量评分	否	是
安装时间	~2 分钟	~10 分钟

轻量模式仅需 Python 和 pip。完整模式需要 Docker，并运行 Distill 服务。详情请参阅设置指南。

快速安装

无需全局安装：

npx -y distill-mcp-server

然后配置 Claude Desktop——分步说明请参阅轻量模式设置或完整模式设置。

配置

将该服务添加到你的 claude_desktop_config.json。

轻量模式 — macOS / Linux：

{
  "mcpServers": {
    "distill-mcp": {
      "command": "npx",
      "args": ["-y", "distill-mcp-server"],
      "env": {
        "DISTILL_MCP_CONFIG": "{\"mode\":\"lightweight\",\"python_path\":\"python3\"}"
      }
    }
  }
}

轻量模式 — Windows：

{
  "mcpServers": {
    "distill-mcp": {
      "command": "npx",
      "args": ["-y", "distill-mcp-server"],
      "env": {
        "DISTILL_MCP_CONFIG": "{\"mode\":\"lightweight\",\"python_path\":\"py\"}"
      }
    }
  }
}

完整模式 — 所有平台：

{
  "mcpServers": {
    "distill-mcp": {
      "command": "npx",
      "args": ["-y", "distill-mcp-server"],
      "env": {
        "DISTILL_MCP_CONFIG": "{\"mode\":\"full\",\"distill_url\":\"http://localhost:7860\"}"
      }
    }
  }
}

完整的配置项参考请见设置指南： 轻量模式 | 完整模式

CLAUDE.md 代码片段

将此内容粘贴到项目的 CLAUDE.md，让 Claude 知道如何自动使用该工具。请原样复制下面的代码块：

## Document Conversion — distill-mcp

When the user references a local file path (e.g. a PDF, DOCX, PPTX, XLSX,
HTML, or audio file), ALWAYS call the `convert_and_save` tool before reading
or reasoning about the document. Do not read the original file directly via
filesystem tools — use only the Markdown returned by `convert_and_save` as
the document content.

### Rules

1. Call `convert_and_save` with the absolute file path before doing anything
   else with the document.
2. Use ONLY the Markdown output from `convert_and_save` as the document
   content. Never read the original file with filesystem tools.
3. If the response includes `"overwritten": true`, tell the user that a
   previous cached version was replaced before proceeding.
4. If the response includes any `warnings`, surface them to the user before
   proceeding with the document content.
5. If `convert_and_save` returns an unsupported format error, tell the user
   which formats are supported and suggest switching modes if applicable.

### Supported formats

| Category | Lightweight | Full (Docker) |
|---|---|---|
| Word | .docx, .doc, .odt | .docx, .doc, .odt |
| Excel | .xlsx, .xlsm, .csv | .xlsx, .xlsm, .csv |
| PowerPoint | .pptx, .ppt | .pptx, .ppt |
| PDF | .pdf (native text) | .pdf (native + scanned OCR) |
| HTML | .html, .htm | .html, .htm |
| Audio | — | .mp3, .wav, .m4a, .flac, .ogg |
| Other | — | .epub, .json, .sql, .wsdl, .wsd |

### Usage

Say "convert using distill" followed by the file path:
> Convert using distill C:\Users\me\Documents\report.pdf to markdown

也可在 docs/CLAUDE.md-snippet.md 中找到该代码片段。

支持的格式

类别	扩展名	轻量模式	完整模式
Microsoft Word	.docx、.doc、.odt	是	是
Microsoft Excel	.xlsx、.xlsm、.csv	是	是
Microsoft PowerPoint	.pptx、.ppt	是	是
PDF（原生文本）	.pdf	是	是
PDF（扫描版/OCR）	.pdf	否	是
HTML	.html、.htm	是	是
音频	.mp3、.wav、.m4a、.flac、.ogg	否	是
EPUB	.epub	否	是
JSON	.json	否	是
SQL	.sql	否	是
WSDL	.wsdl、.wsd	否	是

隐私

所有处理都在本地进行。在轻量模式下，文档由你电脑上的 distill-core Python 库转换——数据不会离开你的电脑。在完整模式下，文档会发送到你电脑上本地运行的 Distill Docker 服务——不会向外部服务发送数据。

构建基础

Distill — 文档转 Markdown 的转换引擎。

许可证

MIT