MDMagic MCP Server

MDMagic MCP 服务

使用你自己的 Word 模板将 Markdown 转换为 DOCX、PDF 和 HTML——包含你的信头、品牌元素和字体。 此外还提供 15 款设计师打造的模板，供你在没有自有模板时使用。

MDMagic 可直接接入 Claude、Cursor、VS Code 和任何兼容 MCP 的 AI 助手，让它们直接使用专业的文档转换流程（Pandoc + Microsoft Graph + Mammoth.js），更重要的是，还能使用你的模板。上传你现有的信头、信纸、品牌指南、合同模板或提案模板——任何你已在 Microsoft Word 中使用的文档——AI 助手就能将任意 Markdown 直接转换为精美文档，并使用你的徽标、字体、颜色、页脚、页码、水印和签名栏。生成的文档看起来就像出自你的设计团队，而不是通用 AI 导出结果。

You: "Take this report and turn it into an Executive_Platinum PDF."

Claude: ✅ Done. Here's your secure download link.
        14-page PDF, 2.3 MB, expires in 60 minutes.

安装

你需要一个 MDMagic 账户（提供免费套餐）以及从账户页面获取的 API 密钥。

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "mdmagic": {
      "command": "npx",
      "args": ["-y", "@mdmagic/mcp-server@latest"],
      "env": {
        "MDMAGIC_API_KEY": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

配置文件位置：

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json
• Linux — ~/.config/Claude/claude_desktop_config.json

重启 Claude Desktop。MDMagic 工具将显示在工具列表中。

Cursor

添加到 ~/.cursor/mcp.json（或通过“设置”→“MCP”添加）：

{
  "mcpServers": {
    "mdmagic": {
      "command": "npx",
      "args": ["-y", "@mdmagic/mcp-server@latest"],
      "env": {
        "MDMAGIC_API_KEY": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

VS Code（配合 MCP 扩展）

{
  "mcp.servers": {
    "mdmagic": {
      "command": "npx",
      "args": ["-y", "@mdmagic/mcp-server@latest"],
      "env": {
        "MDMAGIC_API_KEY": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

托管服务（无需安装）

不想在用户的设备上安装 Node？请使用托管端点：

{
  "mcpServers": {
    "mdmagic": {
      "url": "https://api.mdmagic.ai/mcp",
      "headers": {
        "x-api-key": "mdmagic-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

工具和模板相同，通过 Streamable HTTP 提供服务。适用于不运行本地进程的客户端。

你可以做什么

连接后，可以向 AI 助手提出类似这样的请求：

• “使用 Executive_Platinum 模板将这份 markdown 转换为 PDF。”
• “我有哪些可用模板？”
• “将这份 800 词的报告渲染为 DOCX + PDF 需要多少积分？”
• “使用 Legal_Burgundy 模板，以横向、US Letter 页面格式渲染。”
• “查看我的积分余额。”

AI 会选择合适的工具，并返回安全且有时效限制的下载链接。

工具

工具	功能
convert_document	将 Markdown 转换为 DOCX / PDF / HTML / 全部三种格式。返回安全的限时有效 URL。
validate_markdown	转换前检查。可发现格式错误的表格、未闭合的代码围栏和其他会导致输出异常的语法问题。
estimate_conversion_cost	根据字数、页数、格式和模板类型预估转换费用。
check_credit_balance	当前积分余额（订阅积分 + 已购积分池）和套餐状态。
list_all_templates	完整模板目录：15 款内置模板（按类别分组）+ 你上传的自定义模板。
list_builtin_templates	仅列出内置模板：Business（5 款）、Creative（6 款）、Professional（2 款）、Technical（2 款）。
list_custom_templates	仅列出你上传的自定义模板。
get_template_details	显示指定模板的可用变体（页面尺寸 × 方向）。
recommend_template	根据描述的用途推荐最合适的内置模板（“Q4 board pack” → Executive_Platinum）。
show_default_settings	显示你默认的页面尺寸、方向和模板偏好。

convert_document — 输入选项

提供源内容的三种方式：

• content — 原始 Markdown 字符串（最常用）
• filePath — .md 文件的绝对路径（非常适合 IDE 工作流）
• fileContent — Base64 编码的 Markdown（适用于二进制安全传输）

另外：

• templateName — 例如 Executive_Platinum、Legal_Burgundy 或自定义模板 UUID
• outputFormat — docx、pdf、html、all 或 all-formats
• pageSize — A4、A3、US_Letter、US_Legal、Executive
• orientation — Portrait 或 Landscape

配置

变量	默认值	说明
MDMAGIC_API_KEY	(必填)	你在 mdmagic.ai/account 获取的个人 API 密钥
MDMAGIC_BASE_URL	https://api.mdmagic.ai	仅在本地开发或暂存环境中覆盖
REQUEST_TIMEOUT	30000	请求超时时间，单位为毫秒
MCP_TRANSPORT	stdio	stdio（默认）或用于可自托管 Streamable HTTP 的 http
MCP_HTTP_PORT	3001	HTTP 传输模式的端口
MCP_HTTP_HOST	127.0.0.1	HTTP 传输模式的绑定地址

大多数用户只需设置 MDMAGIC_API_KEY。

定价

转换会消耗额度，费用根据页数和输出格式计算：

• DOCX：每页 1 个额度（基础费用）
• PDF：每页额外 1 个额度
• HTML：每页额外 1 个额度
• 自定义模板：每页额外 1 个额度

一份 5 页的报告使用自定义模板转换为 DOCX + PDF + HTML，费用为 5 × (1 + 1 + 1 + 1) = 20 credits。

estimate_conversion_cost 工具会在你消费额度前返回精确费用。若额度不足，MCP 也会拒绝执行——不会产生意外账单。

免费套餐的额度每月续期。付费套餐和额度充值可在 mdmagic.ai 办理。

隐私

• 不会永久存储。 文档会通过 Microsoft Graph API 进行 PDF 渲染，并在 5–10 秒内删除。输出文件会在下载后删除，或在 60 分钟后删除，以先发生者为准。
• 随机文件名。 源文件使用 UUID 命名，不会使用可识别用户身份的名称。
• 安全下载 URL。 每次转换都会返回一个包含会话 ID 和下载令牌的一次性 URL。不会提供公开文件目录。
• API 密钥隔离。 每位用户都使用自己的密钥进行身份验证，不会共用凭据。

故障排除

MDMAGIC_API_KEY environment variable is required 在客户端配置中设置环境变量（JSON 中的 env 区块）。不要在 shell 中设置——npx 无法读取。

Invalid API key format 密钥必须以 mdmagic- 开头，后接恰好 16 位数字。请从账户页面准确复制。

Failed to connect to MDMagic API 在浏览器中检查 https://api.mdmagic.ai/health。如果服务正常，则问题出在本地网络或防火墙。请确认运行 MCP 的机器可以访问 MDMAGIC_BASE_URL（默认为 https://api.mdmagic.ai）。

工具未显示在 Claude Desktop 中 编辑 claude_desktop_config.json 后，请完全退出并重新启动 Claude Desktop——仅关闭窗口并不足够。

Insufficient credits 使用 check_credit_balance 确认余额，使用 estimate_conversion_cost 预估费用，或前往 mdmagic.ai/account 充值。

本地开发

git clone https://github.com/MDMagic-MCP/mdmagic-mcp-server.git
cd mdmagic-mcp-server
npm install

# Set your API key (use http://localhost:3000 if running the API locally)
cp .env.example .env
# edit .env

# Build and inspect
npm run build
npm run inspector

MCP Inspector（npm run inspector）会启动一个 Web 界面，可逐个测试服务工具，适合添加新工具或调试参数验证。

运行 npm test 执行测试。

链接

• MDMagic — mdmagic.ai
• 获取 API 密钥 — mdmagic.ai/account
• 问题反馈 — github.com/MDMagic-MCP/mdmagic-mcp-server/issues
• MCP 规范 — modelcontextprotocol.io

许可证

MIT — 详见 LICENSE。