使用说明

DOCX MCP服务器

使用Rust构建的用于Microsoft Word DOCX文件操作的综合模型上下文协议（MCP）服务器。该服务器为AI系统提供了强大的工具，可以以编程方式创建、编辑、转换和管理Word文档。

📖 目录

快速开始
AI工具集成
特性
实际使用示例
先决条件
安装
常见用例
可用工具
示例工作流
建筑
发展
故障排除
示例目录
贡献
许可证

🚀 快速开始

# Clone the repository
git clone https://github.com/yourusername/docx-mcp.git
cd docx-mcp

# Download embedded fonts for standalone operation (optional but recommended)
./download_fonts.sh

# Build the server (creates a fully standalone binary)
./build.sh

# The server is now ready - no external dependencies required!

🎯 独立操作

此MCP服务器旨在工作 完全独立 无需LibreOffice、unoconv或任何外部工具：

✅ 纯Rust DOCX解析 -不需要外部库
✅ 内置PDF生成 -不使用LibreOffice创建PDF
✅ 嵌入字体 -二进制文件中包含专业排版
✅ 原生图像处理 -不使用ImageMagick生成PNG/JPG
✅ 零外部依赖 -单二进制部署

如果可以提高质量，服务器将自动使用外部工具，但它们是 完全可选.

🔒 安全功能

该服务器包括适用于企业和受限环境的全面安全功能：

只读模式

# Enable readonly mode - only allows document viewing and analysis

# Using environment variables
export DOCX_MCP_READONLY=true
./target/release/docx-mcp

# Using command line arguments
./target/release/docx-mcp --readonly

在只读模式下，只允许执行以下操作：

打开和查看文档
提取文本并分析结构
导出为其他格式（Markdown、PDF）
搜索和字数分析
获取文档元数据和统计信息

命令筛选

# Whitelist specific commands only

# Using environment variables
export DOCX_MCP_WHITELIST="open_document,extract_text,get_metadata,export_to_markdown"

# Using command line arguments
./target/release/docx-mcp --whitelist open_document,extract_text,get_metadata,export_to_markdown

# Or blacklist dangerous commands

# Using environment variables
export DOCX_MCP_BLACKLIST="save_document,convert_to_pdf,merge_documents"

# Using command line arguments
./target/release/docx-mcp --blacklist save_document,convert_to_pdf,merge_documents

沙盒模式

# Restrict all file operations to temp directory only

# Using environment variables
export DOCX_MCP_SANDBOX=true
./target/release/docx-mcp

# Using command line arguments
./target/release/docx-mcp --sandbox

资源限制

# Set maximum document size (100MB default)

# Using environment variables
export DOCX_MCP_MAX_SIZE=52428800  # 50MB
export DOCX_MCP_MAX_DOCS=20
export DOCX_MCP_NO_EXTERNAL_TOOLS=true
export DOCX_MCP_NO_NETWORK=true
./target/release/docx-mcp

# Using command line arguments
./target/release/docx-mcp \
  --max-size 52428800 \
  --max-docs 20 \
  --no-external-tools \
  --no-network

🤖 AI工具集成

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

使用安全选项（使用命令行参数）：

{
  "mcpServers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": ["--readonly", "--max-size", "52428800", "--no-network"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

使用安全选项（使用环境变量）：

{
  "mcpServers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info",
        "DOCX_MCP_READONLY": "true",
        "DOCX_MCP_MAX_SIZE": "52428800",
        "DOCX_MCP_NO_NETWORK": "true"
      }
    }
  }
}

添加后，重新启动Claude Desktop。然后，您可以要求克劳德：

“使用我们的第四季度报告创建新的Word文档”
“将此DOCX文件转换为PDF”
“从我的Word文档中提取所有文本”
“将包含销售数据的表添加到文档中”

光标

添加到光标设置(~/.cursor/config.json 或通过设置UI）：

基本配置：

{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": [],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}

使用安全选项（使用命令行参数）：

{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": ["--sandbox", "--whitelist", "open_document,extract_text,export_to_markdown"],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}

使用安全选项（使用环境变量）：

{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": [],
        "env": {
          "RUST_LOG": "info",
          "DOCX_MCP_SANDBOX": "true",
          "DOCX_MCP_WHITELIST": "open_document,extract_text,export_to_markdown"
        }
      }
    }
  }
}

风帆冲浪（Codeium）

添加到您的Windsurf配置(~/.windsurf/config.json):

基本配置：

{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": [],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}

使用安全选项（使用参数）：

{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": ["--readonly", "--no-external-tools"],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}

Continue.dev

添加到“继续”配置(~/.continue/config.json):

基本配置：

{
  "models": [
    {
      "title": "Your Model",
      "provider": "your-provider",
      "mcp_servers": {
        "docx": {
          "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
          "args": []
        }
      }
    }
  ]
}

使用安全选项：

{
  "models": [
    {
      "title": "Your Model",
      "provider": "your-provider",
      "mcp_servers": {
        "docx": {
          "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
          "args": ["--sandbox", "--max-size", "10485760"]
        }
      }
    }
  ]
}

带有MCP扩展的VS代码

如果将MCP扩展用于VS Code，请添加到您的工作区设置中(.vscode/settings.json):

基本配置：

{
  "mcp.servers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

使用安全选项：

{
  "mcp.servers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": ["--readonly", "--blacklist", "save_document,merge_documents"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

🔧 命令行参数

DOCX MCP服务器支持以下命令行参数进行配置：

docx-mcp --help

可用参数

参数	环境变量	描述	示例
`--readonly`	`DOCX_MCP_READONLY=true`	启用只读模式-仅查看操作	`--readonly`
`--whitelist <COMMANDS>`	`DOCX_MCP_WHITELIST`	逗号分隔的允许命令列表	`--whitelist open_document,extract_text`
`--blacklist <COMMANDS>`	`DOCX_MCP_BLACKLIST`	以逗号分隔的禁止命令列表	`--blacklist save_document,convert_to_pdf`
`--sandbox`	`DOCX_MCP_SANDBOX=true`	仅将文件操作限制在临时目录	`--sandbox`
`--no-external-tools`	`DOCX_MCP_NO_EXTERNAL_TOOLS=true`	禁用外部工具（LibreOffice等）	`--no-external-tools`
`--no-network`	`DOCX_MCP_NO_NETWORK=true`	禁用网络操作	`--no-network`
`--max-size <BYTES>`	`DOCX_MCP_MAX_SIZE`	最大文档大小（字节）	`--max-size 52428800`
`--max-docs <COUNT>`	`DOCX_MCP_MAX_DOCS`	打开文档的最大数量	`--max-docs 20`
`--help`	-	显示帮助信息	`--help`
`--version`	-	显示版本信息	`--version`

示例用法

# Basic usage
./target/release/docx-mcp

# Readonly mode with size limit
./target/release/docx-mcp --readonly --max-size 10485760

# Sandbox mode with command whitelist
./target/release/docx-mcp --sandbox --whitelist open_document,extract_text,export_to_markdown

# Multiple security options
./target/release/docx-mcp \
  --readonly \
  --no-external-tools \
  --no-network \
  --max-size 52428800 \
  --max-docs 10

注：如果同时指定了命令行参数和环境变量，则命令行参数优先于环境变量。

📚 特性

文档操作

创建并打开：创建新文档或打开现有DOCX文件
文本操作：添加具有完整样式支持的段落、标题、列表
表格：使用自定义布局创建和格式化表格
页面布局：添加分页符，设置页眉/页脚
查找与替换：在整个文档中搜索和替换文本
文本提取：从文档中提取纯文本内容

转换能力

DOCX转PDF：将Word文档转换为PDF格式
- 使用LibreOffice/unoconv进行高保真转换
- 如果外部工具不可用，则回退到基本的PDF生成
DOCX到图像：将文档页面转换为PNG/JPG图像
- 可配置的DPI用于质量控制
- 支持多种图像格式
PDF操作：拆分、合并和操作PDF文件

高级功能

文档元数据：跟踪创建时间、大小、作者等。
造型支持：字体系列、大小、粗体、斜体、下划线、颜色、对齐方式
多个文档：同时处理多个文档
临时文件管理：自动清理临时文件

专业模板

商业信函：格式正确的专业信函
简历：现代简历布局，包括经验、教育、技能部分
报告：带目录的技术和业务报告
发票：具有逐项计费的专业发票模板
合同：带有签名块的法律文件模板
备忘录：公司备忘录格式
通讯：出版物的多列布局

高级文档功能

目录：使用标题链接自动生成TOC
图片和图表：嵌入图像并创建数据可视化
超链接和书签：与导航的内部和外部链接
脚注和尾注：学术和专业引文支持
评论和跟踪更改：文档审查的协作功能
水印：机密、草稿和自定义水印
邮件合并：自动生成个性化文档
自定义样式：创建和应用一致的格式主题

分析和审查工具

文档结构分析：标题和章节概览
格式分析：检测字体、样式和格式不一致
高级搜索：与上下文和定位的模式匹配
字数统计：包括阅读时间在内的详细指标
导出选项：转换为Markdown、HTML和其他格式

💬 AI助手的真实使用示例

使用克劳德桌面

配置后，您可以与Claude进行自然对话：

You: "Create a professional invoice template for my consulting business"

Claude will:
1. Create a new DOCX document
2. Add your company header
3. Insert a table for line items
4. Add payment terms and footer
5. Save it as invoice_template.docx

You: "Convert all the Word documents in my reports folder to PDF"

Claude will:
1. List all DOCX files
2. Open each document
3. Convert to PDF with the same name
4. Report completion status

带光标/风帆

在编码时，您可以生成文档：

You: "Generate API documentation from these TypeScript interfaces and save as Word"

The AI will:
1. Parse your code
2. Create a formatted DOCX with:
   - Title and table of contents
   - Endpoint descriptions
   - Request/response examples
   - Error codes table
3. Convert to PDF for distribution

自动化示例

# Ask your AI: "Create a script to generate monthly reports"
# The AI can use the DOCX server to:

async def generate_monthly_report(month, year):
    # Create document
    doc = await mcp.call("create_document")
    
    # Add dynamic content
    await mcp.call("add_heading", {
        "document_id": doc.id,
        "text": f"Monthly Report - {month} {year}",
        "level": 1
    })
    
    # Add data from your database
    sales_data = fetch_sales_data(month, year)
    await mcp.call("add_table", {
        "document_id": doc.id,
        "rows": format_sales_table(sales_data)
    })
    
    # Convert to PDF and email
    await mcp.call("convert_to_pdf", {
        "document_id": doc.id,
        "output_path": f"reports/{year}_{month}_report.pdf"
    })

📋 先决条件

必需

Rust 1.70+和Cargo（用于从源头建造）
MCP兼容的AI客户端（克劳德桌面、光标、Windsurf等）

完全可选（用于增强功能）

服务器可以独立工作，但如果可用，可以选择使用这些工具：

办公套件 （推荐）：用于高质量的DOCX到PDF转换

# macOS
brew install libreoffice

# Ubuntu/Debian
sudo apt-get install libreoffice

# Windows
# Download from https://www.libreoffice.org/

PDF转图像工具 （其中任何一项）：

pdftoppm（poppler-utils的一部分）
ImageMagick
Ghostscript

# macOS
brew install poppler imagemagick ghostscript

# Ubuntu/Debian
sudo apt-get install poppler-utils imagemagick ghostscript

🔧 安装

方法1：从源代码构建

# Clone the repository
git clone https://github.com/yourusername/docx-mcp.git
cd docx-mcp

# Build the server (uses the build script)
./build.sh

# Or manually with cargo
cargo build --release

# Optional: Enable Chrome-based PDF conversion
cargo build --release --features chrome-pdf

方法2：下载预构建二进制文件（即将推出）

# Download the latest release
curl -L https://github.com/yourusername/docx-mcp/releases/latest/download/docx-mcp-linux-x64 -o docx-mcp
chmod +x docx-mcp

验证安装

# Test the server
./target/release/docx-mcp --version

# Check for optional dependencies
./build.sh

🎯 常见用例

1.文档自动化

生成合同、发票和报告
邮件合并操作
批量文档处理
基于模板的文档创建

2.数据导出

将数据库报告导出为Word/PDF
从JSON/CSV创建格式化文档
使用图表和表格生成测试报告

3.文档转换流程

DOCX → PDF存档
DOCX → 预览图像
遗留文档的批量转换

4.内容管理

提取文本以建立索引
跨多个文档查找和替换
文档元数据管理

5.集成场景

CI/CD文档生成
API代码文档
通过监控工具自动生成报告

可用工具

文档管理

`create_document`

创建新的空DOCX文档。

{
  "tool": "create_document",
  "arguments": {}
}

`open_document`

打开现有的DOCX文件。

{
  "tool": "open_document",
  "arguments": {
    "path": "/path/to/document.docx"
  }
}

`save_document`

将文档保存到指定路径。

{
  "tool": "save_document",
  "arguments": {
    "document_id": "doc_123",
    "output_path": "/path/to/output.docx"
  }
}

内容添加

`add_paragraph`

将样式化段落添加到文档中。

{
  "tool": "add_paragraph",
  "arguments": {
    "document_id": "doc_123",
    "text": "This is a paragraph",
    "style": {
      "font_size": 12,
      "bold": true,
      "color": "#FF0000",
      "alignment": "center"
    }
  }
}

`add_heading`

添加标题（级别1-6）。

{
  "tool": "add_heading",
  "arguments": {
    "document_id": "doc_123",
    "text": "Chapter 1",
    "level": 1
  }
}

`add_table`

使用指定数据创建表。

{
  "tool": "add_table",
  "arguments": {
    "document_id": "doc_123",
    "rows": [
      ["Name", "Age", "City"],
      ["Alice", "30", "New York"],
      ["Bob", "25", "Los Angeles"]
    ],
    "headers": ["Name", "Age", "City"]
  }
}

`add_list`

添加项目符号或编号列表。

{
  "tool": "add_list",
  "arguments": {
    "document_id": "doc_123",
    "items": ["First item", "Second item", "Third item"],
    "ordered": true
  }
}

文档转换

`convert_to_pdf`

将文档转换为PDF格式。

{
  "tool": "convert_to_pdf",
  "arguments": {
    "document_id": "doc_123",
    "output_path": "/path/to/output.pdf"
  }
}

`convert_to_images`

将文档页面转换为图像。

{
  "tool": "convert_to_images",
  "arguments": {
    "document_id": "doc_123",
    "output_dir": "/path/to/images/",
    "format": "png",
    "dpi": 300
  }
}

文本操作

`extract_text`

从文档中提取所有文本内容。

{
  "tool": "extract_text",
  "arguments": {
    "document_id": "doc_123"
  }
}

`find_and_replace`

查找并替换文档中的文本。

{
  "tool": "find_and_replace",
  "arguments": {
    "document_id": "doc_123",
    "find_text": "old text",
    "replace_text": "new text"
  }
}

示例工作流

创建报告

// 1. Create a new document
const doc = await mcp.call("create_document", {});

// 2. Add title
await mcp.call("add_heading", {
  document_id: doc.document_id,
  text: "Annual Report 2024",
  level: 1
});

// 3. Add executive summary
await mcp.call("add_paragraph", {
  document_id: doc.document_id,
  text: "This report provides a comprehensive overview...",
  style: { font_size: 12, alignment: "justify" }
});

// 4. Add data table
await mcp.call("add_table", {
  document_id: doc.document_id,
  rows: [
    ["Quarter", "Revenue", "Growth"],
    ["Q1", "$1.2M", "15%"],
    ["Q2", "$1.5M", "25%"]
  ]
});

// 5. Convert to PDF
await mcp.call("convert_to_pdf", {
  document_id: doc.document_id,
  output_path: "./annual_report_2024.pdf"
});

批处理文档

// Open and convert multiple documents
const documents = ["doc1.docx", "doc2.docx", "doc3.docx"];

for (const docPath of documents) {
  const doc = await mcp.call("open_document", { path: docPath });
  
  // Extract text for analysis
  const text = await mcp.call("extract_text", { 
    document_id: doc.document_id 
  });
  
  // Convert to PDF
  await mcp.call("convert_to_pdf", {
    document_id: doc.document_id,
    output_path: docPath.replace(".docx", ".pdf")
  });
  
  // Generate thumbnails
  await mcp.call("convert_to_images", {
    document_id: doc.document_id,
    output_dir: "./thumbnails/",
    format: "jpg",
    dpi: 72
  });
  
  await mcp.call("close_document", { document_id: doc.document_id });
}

建筑

服务器采用模块化架构构建：

main.rs：MCP服务器设置和初始化
docx_handler.rs：核心DOCX操作逻辑
converter.rs：PDF和图像转换功能
docx_tools.rs：MCP工具定义和处理程序

发展

从源头构建

cargo build

运行测试

cargo test

调试模式

RUST_LOG=debug cargo run

🐛 故障排除

AI工具特定问题

Claude Desktop无法识别服务器

确保配置中的路径是绝对的，而不是相对的
配置更改后重新启动Claude Desktop
检查日志： tail -f ~/Library/Logs/Claude/mcp.log （macOS）
验证二进制文件是否可执行： chmod +x /path/to/docx-mcp

光标/风帆连接问题

检查MCP服务器是否正在运行： ps aux | grep docx-mcp
验证端口可用性： lsof -i :3000
尝试重新加载窗口： Cmd/Ctrl + R
检查开发人员控制台是否有错误： Cmd/Ctrl + Shift + I

“找不到工具”错误

确保服务器在您的AI工具中配置正确
检查服务器是否正在运行： RUST_LOG=debug /path/to/docx-mcp
验证工具名称是否完全匹配（区分大小写）

转换问题

找不到LibreOffice

# Check if installed
which libreoffice

# Install if missing
# macOS
brew install libreoffice

# Ubuntu/Debian
sudo apt-get install libreoffice

# Fedora
sudo dnf install libreoffice

PDF到图像转换失败

# Install at least one converter
# Option 1: pdftoppm (fastest)
sudo apt-get install poppler-utils  # Linux
brew install poppler                 # macOS

# Option 2: ImageMagick
sudo apt-get install imagemagick     # Linux
brew install imagemagick              # macOS

# Option 3: Ghostscript
sudo apt-get install ghostscript     # Linux
brew install ghostscript              # macOS

权限错误

# Check temp directory permissions
ls -la /tmp/docx-mcp/

# Fix permissions if needed
mkdir -p /tmp/docx-mcp
chmod 755 /tmp/docx-mcp

# For system-wide installation
sudo chown $USER:$USER /tmp/docx-mcp

大型文档的内存问题

# Increase Rust stack size if needed
export RUST_MIN_STACK=8388608  # 8MB
./target/release/docx-mcp

调试提示

# Run with verbose logging
RUST_LOG=trace ./target/release/docx-mcp

# Test with the example client
python3 example/test_client.py

# Check MCP communication
RUST_LOG=mcp_server=debug ./target/release/docx-mcp

📁 示例目录

这 example/ 目录包含全面的示例和模板：

包含的文件

test_client.py -Python客户端测试所有MCP服务器功能
claude_examples.md -Claude Desktop用户的真实示例
config_examples.json -所有支持的AI工具的配置模板
automation_example.py -高级自动化工作流程包括：
- 月度报告生成
- 邮件合并操作
- 文件处理管道
- 合同生成

运行示例

# Test the server functionality
python3 example/test_client.py

# Run automation examples
python3 example/automation_example.py

# View Claude Desktop usage examples
cat example/claude_examples.md

示例类别

基本操作：创建、编辑、保存文档
格式化：样式、表格、列表、页眉/页脚
转换：DOCX转PDF，DOCX转图像
自动化：批处理、邮件合并、报告生成
整合：处理CSV数据、模板处理

🤝 贡献

我们欢迎捐款！以下是您可以提供帮助的方式：

贡献领域

其他文档操作功能
支持更多转换格式
性能优化
文档改进
Bug修复和测试

如何做出贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发设置

# Clone your fork
git clone https://github.com/yourusername/docx-mcp.git
cd docx-mcp

# Install development dependencies
cargo install cargo-watch cargo-expand

# Run tests
cargo test

# Run with watch mode for development
cargo watch -x run

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

与官方合作建造 MCP Rust SDK
用途 docx-rs 用于DOCX操作
PDF生成打印pdf
图像处理图像rs