DOCX-MCP

# DOCX-MCP: Word Document MCP Server A Model Context Protocol (MCP) server for Microsoft Word document operations, built with FastMCP and python-docx. Focused on advanced table operations with comprehensive formatting and analysis capabilities. ## 🚀 Core Features ### Document Operations - `open_document` - Open/create Word documents - `save_document` - Save documents with optional rename - `get_document_info` - Get document information and metadata ### Table Structure Operations - `create_table` - Create tables with customizable dimensions and headers - `delete_table` - Delete tables by index - `add_table_rows` - Add/remove rows at any position with styling - `add_table_columns` - Add/remove columns at any position with styling - `delete_table_rows` - Delete specific rows from tables - `merge_cells` - Merge cells in rectangular regions - `unmerge_cells` - Split merged cell regions back into individual cells ### Table Data Operations - `set_cells_value` - Batch set multiple cells efficiently with comprehensive formatting options - `get_table_data_and_structure` - Get table data and structure (array, object, CSV formats) - `get_table_styles` - Get table cell styles and formatting information - `list_tables` - List all tables with metadata ### Table Search & Analysis - `search_table_content` - Search content across all table cells - `search_table_headers` - Search specifically in table headers ### Cell Formatting Features - **Text Formatting**: Font family, size, color, bold, italic, underline, strikethrough - **Alignment**: Horizontal (left, center, right, justify) and vertical (top, middle, bottom) - **Visual Styling**: Background colors (hex), borders with customizable styles/widths/colors - **Style Preservation**: Maintain existing formatting when updating cells - **Batch Operations**: Efficiently set multiple cells with individual formatting in one call ## 📦 Installation ```bash # Clone and install git clone <repository-url> cd docx_table pip install -r requirements.txt pip install -e . ``` ## 🖥️ Usage ### Run MCP Server ```bash # 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 ``` ### Command Line Options ```bash python -m docx_mcp.server --help ``` **Available options:** - `--transport {stdio,sse,streamable-http}` - Transport protocol (default: stdio) - `--host HOST` - Host for HTTP/SSE transports (default: localhost) - `--port PORT` - Port for HTTP/SSE transports (default: 8000) - `--no-banner` - Disable startup banner ### Direct Usage ```python 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 Tools All tools work independently - no pre-loading required. Each tool accepts JSON parameters and returns JSON responses. ### Interface Design Philosophy The MCP interface is designed for **efficiency and simplicity**: - **Batch Operations**: Use `set_cells_value` for setting multiple cells efficiently - **Data/Style Separation**: Use `get_table_data_and_structure` for content and `get_table_styles` for formatting - **Range Queries**: Both data and style interfaces support row/column ranges for large tables - **Context-Aware**: Optimized for AI model usage with minimal API calls ### Document Operations - `open_document(file_path, create_if_not_exists=True)` - Open/create Word documents - `save_document(file_path, save_as=None)` - Save documents with optional rename - `get_document_info(file_path)` - Get document information and metadata ### Table Operations - `create_table(file_path, rows, cols, headers=None)` - Create tables with headers - `delete_table(file_path, table_index)` - Delete tables by index - `add_table_rows(file_path, table_index, count, position="end")` - Add/remove rows - `add_table_columns(file_path, table_index, count, position="end")` - Add/remove columns - `delete_table_rows(file_path, table_index, row_indices)` - Delete specific rows ### Data Operations - `set_cells_value(file_path, table_index, cells)` - Batch set multiple cells with formatting - `get_table_data_and_structure(file_path, table_index, format="array")` - Get table data and structure (array/object/CSV) - `get_table_styles(file_path, table_index)` - Get table cell styles and formatting - `list_tables(file_path)` - List all tables with metadata ### Cell Merge Operations - `merge_cells(file_path, table_index, start_row, start_col, end_row, end_col)` - Merge cells in rectangular regions - `unmerge_cells(file_path, table_index, row, column)` - Split merged cell regions back into individual cells ### Search & Analysis - `search_table_content(file_path, query, search_mode="contains")` - Search table content - `search_table_headers(file_path, query)` - Search table headers ## 🧪 Testing ```bash pytest # Run all tests pytest --cov=src/docx_mcp # Run with coverage pytest -v # Verbose output ``` ## 📄 License MIT License - see LICENSE file for details.