MDisBetter file converter

mdisbetter MCP 服务

一个让 Agent 转换文件的 MCP 服务。它通过标准输入/输出提供 mdisbetter.com 转换器：已验证 162 种输入格式之间的 3649 种转换。支持图像、文档、电子书、音频、视频、办公文件、字体、存档文件、数据格式、字幕和参考书目。涵盖 11 个类别，支持双向转换，不仅限于 PDF。

只有两个工具，功能就这么多：

工具	功能
convert_file	接收文件路径和输出格式，写入转换后的文件，并返回其路径。
list_conversions	指定扩展名时，返回已验证支持的输出格式；不指定时，返回所有接受的输入扩展名。

不支持的功能

列出这些内容，是因为不小心就容易让人误以为支持相反的功能。此服务没有批处理模式、没有 Webhook、没有任务轮询、没有队列、没有流式处理、没有 URL 输入，也没有标准输入/输出入口以外的命令行接口。每次调用只转换一个本地文件，并等待结果。

这里以前写着“不支持音频或视频转换”。转换表重新同步后，这句话就不再成立：音频和视频与其他类别一样都可以转换。需要重新编码的视频源时长上限为 120 秒，因为重新编码会消耗实际 CPU 资源；仅更改容器且保留编解码器时则是流复制，不受此限制。

要求

• Node.js 20 或更高版本。
• mdisbetter.com 账户和 API 密钥。需要注册；密钥以 mdb_sk_ 开头。

请在控制面板的 API 密钥页面创建密钥。明文密钥只会显示一次，此后不再显示：系统只存储其哈希值，因此包括我们在内的任何人都无法为你找回密钥。关闭面板前请先妥善保存。

转换会从与网站共用的余额中扣除点数。程序化使用没有单独的额度。

安装

git clone https://github.com/dresseurmonster2-oss/mdisbetter-mcp.git
cd mdisbetter-mcp
npm install

也可以不克隆仓库，直接运行：

npx -y github:dresseurmonster2-oss/mdisbetter-mcp

作为 MCP 捆绑包

支持打开 .mcpb 捆绑包的客户端，可以从每个版本发布页安装此服务：下载 mdisbetter-mcp.mcpb，打开后按提示输入 API 密钥。此捆绑包包含的代码与本仓库相同，并附带所有依赖项；你也可以使用 npm run bundle 自行构建。

此服务已列入官方 MCP Registry，名称为 io.github.dresseurmonster2-oss/mdisbetter-mcp。

配置

两个环境变量，其中一个可选。

变量	必需	含义
MDISBETTER_API_KEY	是	你的密钥，以 mdb_sk_ 开头。
MDISBETTER_BASE_URL	否	默认为 https://mdisbetter.com。可将其指向预览部署环境进行测试。

密钥从服务环境中读取，不会作为工具参数传入。此服务不会将密钥写入输出文件。请妥善保管客户端配置；如果密钥泄露，请在控制面板中撤销。

接入客户端

大多数 MCP 客户端都能读取类似这样的 JSON 配置块。路径应填写克隆仓库的位置。

{
  "mcpServers": {
    "mdisbetter": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/src/index.js"],
      "env": {
        "MDISBETTER_API_KEY": "mdb_sk_your_key_here"
      }
    }
  }
}

重启客户端。list_conversions 和 convert_file 会出现在工具列表中。

工具

list_conversions

// every input format the converter accepts
{ "name": "list_conversions", "arguments": {} }

// what a .docx can become
{ "name": "list_conversions", "arguments": { "extension": "docx" } }

扩展名可带点或不带点，也不区分大小写。.DOCX、docx 和 .docx 表示同一种查询。

如果转换器无法读取某个扩展名，则会拒绝该查询，而不是返回空列表。

convert_file

{
  "name": "convert_file",
  "arguments": {
    "path": "/home/me/report.docx",
    "target": "pdf"
  }
}

参数	必填	含义
path	是	要转换的文件，位于运行此服务的机器上。
target	是	输出格式，填写不带点号的扩展名：pdf、png、md。
output_path	否	结果的写入位置。若文件已存在，则会覆盖。

如果未指定 output_path，结果会以新的扩展名写在输入文件旁边：report.docx 会在同一目录中变为 report.pdf。如果该文件名已被占用，服务会改写入 report-1.pdf。它绝不会覆盖未指定的文件，也绝不会更改输入文件。

服务会拒绝超过 150 MB 的本地输入文件。如果账户套餐或转换类型的限制更严格，则实际限制会更低：Free 账户的文件限制为 10 MB，文档转换类型的限制为 25 MB。服务端上限并不意味着所有格式或账户都能使用 150 MB。

文件小于 4 MB 时，会随请求本身传输，只需一次往返。超过 4 MB 时，服务会先将文件上传到存储空间，再仅发送地址，因为承载该 API 的平台将请求正文和响应正文都限制在 4.5 MB。按 100 KB 的步进于 31/08/2026 测得：4.2 MB 可以通过，4.3 MB 会返回 413 错误，且函数甚至尚未运行。直到那天，本 README 都声称限制为 25 MB；这个数值取自引擎，但通过传输层实际上无法达到。

如果某种格式组合不在表格中，系统会在发送任何内容之前拒绝请求，并列出可用的目标格式：

.png to .docx is not a proven conversion. Proven targets for .png (28):
avif, bmp, dds, eps, gif, hdr, ico, jng, jp2, jpeg, jpg, miff, pbm, pcx,
pdf, pgm, pnm, ppm, ps, psd, ras, sgi, tga, tif, tiff, wbmp, webp, xpm.

演示：将本地 HTML 转换为 Markdown

1. 在你的控制面板注册或登录，创建 API 密钥，并在密钥显示时保存。按上述说明配置 MCP 客户端，然后重启客户端。请勿将密钥放入提示词或源代码管理中。
2. 在运行服务的机器上，将以下自有示例保存为 field-notes.html：

<html><body><h1>Harbor field notes</h1><p>Inspection marker: MCPCA0420261013. Tide reading: 42 centimetres.</p><h2>Actions</h2><ul><li>Check the north gate.</li><li>Record the reading.</li></ul></body></html>

3. 让客户端按顺序调用以下工具。将输入路径替换为实际的绝对路径；在 Windows 上使用带盘符的路径：

{"name":"list_conversions","arguments":{"extension":"html"}}
{"name":"convert_file","arguments":{"path":"/absolute/path/field-notes.html","target":"md"}}

请确认第一个答复在转换前列出了 md。第二个答复会报告文件的写入位置。打开该 Markdown 文件，检查标题、读数和两项操作内容。这些是 MCP 工具参数，并非独立的公共 HTTP 接口或独立转换命令。

经验证的输出如下：

# Harbor field notes

Inspection marker: MCPCA0420261013. Tide reading: 42 centimetres.

## Actions

-   Check the north gate.
-   Record the reading.

于 2026 年 10 月 13 日（新加坡时间）根据源代码 84b2bed 和生产环境进行验证：一个新注册的普通 Free 账户初始有 50 个额度。列出 HTML 目标格式不消耗额度；通过真实 stdio 转换此文件消耗了 0.5 个额度，并写入了 151 字节。使用普通网站会话进行身份验证的相同转换也消耗了 0.5 个额度，并返回了完全相同的字节内容。标题、标记、42 厘米读数和两项操作内容均得以保留。不支持的 HTML 转 PNG 请求没有写入文件，且未消耗额度。测试密钥随后已撤销，合成账户也已停用。

这个简单的 HTML 示例并不能证明目录中的所有格式组合、大文件上传、付费套餐限制、你的客户端配置或复杂文档的保真度。测试未提高任何账户额度。使用每个结果前请先检查；显式指定的 output_path 会替换该路径下的现有文件。

文件未能返回时

服务端会转换每个回答，而不是直接传回状态码。

情况	告知 Agent 的内容
积分用尽	转换需要多少积分、还剩多少积分、还缺多少积分，以及充值页面。这不是故障：账户只是积分用尽，转换并未进行。
密钥被拒绝	密钥缺失、无效或已撤销。请设置 MDISBETTER_API_KEY。
文件被拒绝	该格式对已验证可用，因此问题出在文件本身：内容与扩展名不匹配，或引擎无法读取该文件。
文件过大	超出本地服务上限、账户套餐限制或转换类别限制。
转换器容量已满	服务会主动减载，而不会降低服务质量。没有发生故障，也没有扣费，请几秒后重试。
服务不可用或超时	明确说明情况，且不会写入文件。

除非转换后的文件确实已返回且包含字节，否则绝不会将任何内容写入磁盘。

转换表的来源

src/formats.js 是网站自身使用的表格副本。该表格由程序生成，而非手工编写；其中仅包含经过实际探测、成功转换并读回的格式对，同时会检查输出是否确实为其声称的格式。引擎仅仅宣称支持的格式不会被纳入。

请勿编辑该文件。请在主仓库中重新生成：

python scripts/generer-formats.py

这会根据探测结果重写 site/content/formats.js，然后将该文件原样复制到此处，并保留其原始标头。

该表格会将每个格式对映射到四个端点之一，端点的选择依据是哪个最适合处理该格式对，而非文件所属的类别：

端点	格式对数量	通常处理
/api/convert-image	1189	图像转图像
/api/convert-media	1117	音频和视频
/api/convert-document	895	标记语言和文档格式
/api/convert-ebook	298	电子书和阅读器格式
/api/convert-office	41	办公文档、电子表格和幻灯片
/api/convert-archive	30	归档文件：ZIP、TAR 及其压缩格式、7z
/api/convert-subtitle	25	字幕：SRT、VTT、ASS、SSA、LRC 和 TTML
/api/convert-data	24	数据格式：JSON、YAML、TOML、CSV、TSV、NDJSON
/api/convert-font	18	字体：TrueType、OpenType、WOFF 和 WOFF2
/api/convert-bibliography	12	书目格式：BibTeX、BibLaTeX、CSL JSON、RIS 和 EndNote XML

这些数量会由 test/readme.test.mjs 对照表格进行检查。表格本身是通过对真实引擎进行探测生成的，因此这里的数字过时意味着 README 未更新，而不意味着表格有误。

有些扩展名可以由多个端点处理。.docx 转 PDF 会使用办公端点，因为这样能保留版式；.docx 转 Markdown 则会使用文档端点，因为这样能忠实保留文本。调用方无需了解这些细节：只需指定文件和目标格式。

测试

npm test

测试套件可离线运行。它会将服务端作为真实进程启动，并通过标准输入输出与其进行 MCP 通信；检查全部 3649 个格式对的路由，确认未经验证的格式对会在发出任何请求之前被拒绝，并检查每种回答的措辞，包括确认绝不会将积分用尽描述为失败。

测试不会执行真实转换。这需要密钥和积分余额，而这两者都不应出现在测试套件中。

许可证

MIT。请参阅 LICENSE。

转换器本身是一项托管服务；此仓库是用于连接该服务的连接器。转换会消耗你在 mdisbetter.com 账户中的积分。