Cursor配置markdown转Word的MCP工具教程

Cursor 配置 Markdown 转 Word 的 MCP 工具教程（保姆级，2025 年最新版）

Cursor AI（一个基于 VS Code 的 AI 代码编辑器）通过 Model Context Protocol (MCP) 支持外部工具集成。MCP 允许 Cursor 的 AI 代理（Composer）调用自定义服务器，实现文件转换等高级功能。

注意：直接的“Markdown 转 Word” MCP 工具较少（多数 MCP 专注 Markdown 输出，如 Microsoft 的 MarkItDown），但你可以使用 Pandoc MCP 服务器（开源工具，支持 100+ 格式双向转换，包括 Markdown → DOCX）。Pandoc 是黄金标准，转换质量高，保留格式（如标题、表格、列表）。

本教程基于 Cursor 官方文档和社区工具（如 Playbooks MCP 仓库）。预计时间：10-15 分钟。适用于 Windows/macOS/Linux（需 Node.js/Python）。

一、准备工作

1. 安装 Cursor：

• 下载：https://cursor.com/download
• 安装后，打开 Cursor，登录你的 OpenAI/Anthropic API 密钥（设置 > AI Settings）。

1. 安装依赖：

• Node.js（v18+）：https://nodejs.org/（Pandoc MCP 需要）。
• Pandoc（转换核心）：https://pandoc.org/installing.html
  • Windows：下载 MSI 安装包。
  • macOS：brew install pandoc。
  • Linux：sudo apt install pandoc（Ubuntu）或 sudo dnf install pandoc（CentOS）。
• 验证：终端运行 pandoc --version，看到版本号即 OK。

1. 启用 MCP：

• Cursor > Settings（Ctrl/Cmd + ,） > 搜索 “MCP” > 启用 “MCP Servers”。

二、安装 Pandoc MCP 服务器

Pandoc MCP 是专为 AI 代理设计的服务器，支持 Markdown → Word（DOCX）转换。来源：Playbooks MCP 仓库（https://playbooks.com/mcp/vivekvells-mcp-pandoc）。

1. 克隆/下载服务器：

• 终端运行：
  git clone https://github.com/vivekvells/mcp-pandoc.git cd mcp-pandoc npm install
• 或直接下载 ZIP：https://github.com/vivekvells/mcp-pandoc/archive/refs/heads/main.zip

1. 构建服务器（可选，但推荐）：

   npm run build

3. 测试服务器（本地运行）：

   npm start

• 看到 “MCP Server running on stdio” 即成功。按 Ctrl+C 停止。

三、在 Cursor 中配置 MCP 服务器

有两种方式：全局配置（所有项目可用）或项目配置（单项目）。

1. 全局配置（推荐）：

• 创建文件：~/.cursor/mcp.json（macOS/Linux）或 %USERPROFILE%\.cursor\mcp.json（Windows）。
• 内容（替换路径为你的 mcp-pandoc 目录）：
  json { "mcpServers": { "pandoc-converter": { "command": "node", "args": [ "/path/to/mcp-pandoc/dist/index.js" ], "env": { "PANDOC_PATH": "/usr/local/bin/pandoc" // 替换为你的 Pandoc 路径，运行 `which pandoc` 查询 } } } }
• 保存后，重启 Cursor。

1. 项目配置（如果只用于特定项目）：

• 在项目根目录创建 .cursor/mcp.json，内容同上。

1. 在 Cursor UI 中添加/刷新：

• Settings > Tools & Integrations > MCP Tools > 点击 “New MCP Server” 或 “Refresh”。
• 看到 “pandoc-converter” 服务器及工具列表（如 convert_document）即成功。

四、使用 MCP 工具转换 Markdown 转 Word

Cursor 的 Composer AI 会自动检测并调用工具。

1. 打开 Composer：

• Ctrl/Cmd + L（或侧边栏 Chat 图标）。

1. 提示 AI 转换（自然语言即可）：

• 示例提示： 使用 Pandoc 工具将以下 Markdown 转换为 Word 文档，并保存到桌面作为 output.docx： # 标题 这是一个 **粗体** 段落。 - 列表项 1 - 列表项 2 | 表格 | 列1 | 列2 | |------|-----|-----| | 行1 | A | B |
• AI 会：
  • 识别工具：convert_document（输入：Markdown 字符串，输出格式：DOCX，选项：number-sections: true, toc: true）。
  • 调用 MCP 服务器。
  • 生成 DOCX 文件（路径如 /path/to/output.docx）。

1. 高级选项（在提示中指定）：

• YAML 元数据：添加标题、作者等。
  示例：from: markdown to: docx metadata: title: "My Doc" author: "You"
• 输出路径：必须指定（如 output_file: ~/Desktop/myfile.docx），否则默认临时文件。
• 其他格式：支持 PDF、HTML 等（to: pdf）。

1. 手动调用工具（如果 AI 不自动）：

• 在 Composer 中：@pandoc-converter Convert this Markdown to DOCX: [你的 MD 内容]

1. 验证输出：

• 检查生成的 DOCX：打开 Word，确认格式保留（标题、粗体、表格）。
• 如果出错：查看 Composer 展开的工具调用日志（箭头图标）。

五、常见问题解决

问题	原因 & 解决
服务器未检测到	未刷新 MCP 设置，或路径错。解决：重启 Cursor，检查 mcp.json 语法（JSON 格式）。
Pandoc 命令未找到	PATH 未设置。解决：export PATH=$PATH:/usr/local/bin（macOS），重启终端。
转换失败（无格式）	输入非标准 MD。解决：用 Pandoc 选项如 toc: true。
权限错误（保存文件）	输出路径无写权限。解决：用绝对路径，如 ~/Desktop/。
AI 不调用工具	提示不明确。解决：明确说 “use pandoc tool to convert”。启用 Auto-run（Settings > MCP > Auto-run tools）。
Windows 路径问题	用双反斜杠。解决："C:\\Users\\You\\AppData\\Local\\Programs\\pandoc\\pandoc.exe"。

六、替代方案（如果 Pandoc 不行）

• MarkItDown MCP（Microsoft 官方，但主要是 Doc → MD，反向需结合其他）：https://github.com/microsoft/markitdown-mcp。安装：pip install markitdown-mcp，配置类似。
• 自定义 MCP：用 Python SDK 建服务器（https://modelcontextprotocol.io/docs），集成 Pandoc CLI。
• 非 MCP 方式：Cursor 内置导出（File > Export > Word），但无 AI 自动化。

七、扩展提示

• 批量转换：提示 “Convert all .md files in current folder to DOCX using Pandoc”。
• 集成工作流：结合 Cursor Rules（.cursor/rules.md）自动化文档生成。
• 资源：
• 官方 MCP 文档：https://docs.cursor.com/context/model-context-protocol
• Pandoc MCP GitHub：https://github.com/vivekvells/mcp-pandoc
• 社区：Reddit r/cursor 或 Playbooks MCP 目录。

配置好后，你的 Cursor 就能像“智能文档工厂”一样，一键转 Word！如果卡壳，贴错误日志我帮 debug。享受 AI 编程乐趣！ 🚀