AI导哈

Word文档表格处理服务

一个基于FastMCP和python-docx的Word文档操作MCP服务器，专注于高级表格操作，提供全面的格式化和分析功能。

  • by Rookie0x80
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 Rookie0x80/docx-mcp

使用说明

DOCX-MCP：Word 文档 MCP 服务器

一个用于Microsoft Word文档操作的模型上下文协议（MCP）服务器，采用FastMCP和python-docx构建。专注于高级表格操作，具备全面的格式化和分析功能。

🚀 核心功能

文档操作

  • open_document - 打开/创建Word文档
  • save_document - 保存文档并可选择重命名
  • get_document_info - 获取文档信息和元数据

表结构操作

  • create_table - 创建具有可自定义尺寸和表头的表格
  • delete_table - 通过索引删除表
  • add_table_rows - 在任意位置添加/删除带样式的行
  • add_table_columns - 在任意位置添加/删除带样式的列
  • delete_table_rows - 从表中删除特定行
  • merge_cells - 合并矩形区域内的单元格
  • unmerge_cells - 将合并的单元格区域拆分为单独的单元格

表格数据操作

  • set_cells_value - 批量设置多个单元格，提供全面的格式化选项
  • get_table_data_and_structure - 获取表格数据和结构（数组、对象、CSV格式）
  • get_table_styles - 获取表格单元格的样式和格式化信息
  • list_tables - 列出所有带有元数据的表

表格搜索与分析

  • search_table_content - 在所有表格单元格中搜索内容
  • search_table_headers - 特别是在表格标题中进行搜索

单元格格式化功能

  • 文本格式化字体、字号、颜色、加粗、斜体、下划线、删除线
  • 对齐水平（左对齐、居中、右对齐、两端对齐）和垂直（顶部对齐、居中、底部对齐）
  • 视觉造型背景颜色（十六进制），边框样式/宽度/颜色可自定义
  • 风格保持在更新单元格时保持现有格式
  • 批处理操作在一个调用中高效地设置多个单元格的独立格式

📦 安装

# Clone and install
git clone <repository-url>
cd docx_table
pip install -r requirements.txt
pip install -e .

🖥️ 使用方法

运行MCP服务器

# Default STDIO transport
python -m docx_mcp.server

# HTTP/SSE transports
python -m docx_mcp.server --transport sse --host localhost --port 8000
python -m docx_mcp.server --transport streamable-http --host localhost --port 8000

命令行选项

python -m docx_mcp.server --help

可用选项：

  • --transport {stdio,sse,streamable-http} - 传输协议（默认：stdio）
  • --host HOST - HTTP/SSE 传输的主机（默认：localhost）
  • --port PORT - 用于HTTP/SSE传输的端口（默认：8000）
  • --no-banner - 禁用启动横幅

直接使用

from docx_mcp.core.document_manager import DocumentManager
from docx_mcp.operations.tables.table_operations import TableOperations

# Initialize
doc_manager = DocumentManager()
table_ops = TableOperations(doc_manager)

# Create table with headers (auto-loads document)
result = table_ops.create_table("document.docx", rows=3, cols=4, 
                               headers=["Name", "Age", "City", "Occupation"])

# Set multiple cells with formatting
cells = [
    {"row_index": 1, "column_index": 0, "value": "Alice", "font_family": "Arial", "bold": True},
    {"row_index": 1, "column_index": 1, "value": "25", "font_size": 12}
]
result = table_ops.set_cells_value("document.docx", 0, cells)

# Get table data and structure
result = table_ops.get_table_data_and_structure("document.docx", 0, include_headers=True)

# Merge cells in a 2x2 region (rows 1-2, cols 1-2)
result = table_ops.merge_cells("document.docx", 0, 1, 1, 2, 2)

# Unmerge cells (specify any cell in the merged region)
result = table_ops.unmerge_cells("document.docx", 0, 1, 1)

🔧 MCP 工具

所有工具均独立工作，无需预加载。每个工具都接受JSON参数并返回JSON响应。

界面设计哲学

MCP接口旨在用于 效率与简洁：

  • 批量操作使用 set_cells_value 为了高效地设置多个单元格
  • 数据/样式分离使用 get_table_data_and_structure 对于内容和 get_table_styles 用于格式化
  • 范围查询数据和样式界面均支持大型表格中的行/列范围
  • 情境感知优化用于AI模型，API调用最少

文档操作

  • open_document(file_path, create_if_not_exists=True) - 打开/创建Word文档
  • save_document(file_path, save_as=None) - 保存文档并可选择重命名
  • get_document_info(file_path) - 获取文档信息和元数据

表操作

  • create_table(file_path, rows, cols, headers=None) - 创建带有表头的表格
  • delete_table(file_path, table_index) - 通过索引删除表
  • add_table_rows(file_path, table_index, count, position="end") - 添加/删除行
  • add_table_columns(file_path, table_index, count, position="end") - 添加/删除列
  • delete_table_rows(file_path, table_index, row_indices) - 删除特定行

数据操作

  • set_cells_value(file_path, table_index, cells) - 批量设置多个单元格并应用格式
  • get_table_data_and_structure(file_path, table_index, format="array") - 获取表格数据和结构（数组/对象/CSV）
  • get_table_styles(file_path, table_index) - 获取表格单元格样式和格式
  • list_tables(file_path) - 列出所有带有元数据的表

单元格合并操作

  • merge_cells(file_path, table_index, start_row, start_col, end_row, end_col) - 合并矩形区域内的单元格
  • unmerge_cells(file_path, table_index, row, column) - 将合并的单元格区域拆分成单独的单元格

搜索与分析

  • search_table_content(file_path, query, search_mode="contains") - 搜索表内容
  • search_table_headers(file_path, query) - 搜索表格标题

🧪 测试

pytest                    # Run all tests
pytest --cov=src/docx_mcp # Run with coverage
pytest -v                 # Verbose output

📄 许可证

MIT 许可证 - 详情请参见 LICENSE 文件。

相关 MCP