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 documentssave_document- Save documents with optional renameget_document_info- Get document information and metadata
Table Structure Operations
create_table- Create tables with customizable dimensions and headersdelete_table- Delete tables by indexadd_table_rows- Add/remove rows at any position with stylingadd_table_columns- Add/remove columns at any position with stylingdelete_table_rows- Delete specific rows from tablesmerge_cells- Merge cells in rectangular regionsunmerge_cells- Split merged cell regions back into individual cells
Table Data Operations
set_cells_value- Batch set multiple cells efficiently with comprehensive formatting optionsget_table_data_and_structure- Get table data and structure (array, object, CSV formats)get_table_styles- Get table cell styles and formatting informationlist_tables- List all tables with metadata
Table Search & Analysis
search_table_content- Search content across all table cellssearch_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
# Clone and install
git clone <repository-url>
cd docx_table
pip install -r requirements.txt
pip install -e .
🖥️ Usage
Run MCP Server
# 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
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
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_valuefor setting multiple cells efficiently - Data/Style Separation: Use
get_table_data_and_structurefor content andget_table_stylesfor 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 documentssave_document(file_path, save_as=None)- Save documents with optional renameget_document_info(file_path)- Get document information and metadata
Table Operations
create_table(file_path, rows, cols, headers=None)- Create tables with headersdelete_table(file_path, table_index)- Delete tables by indexadd_table_rows(file_path, table_index, count, position="end")- Add/remove rowsadd_table_columns(file_path, table_index, count, position="end")- Add/remove columnsdelete_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 formattingget_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 formattinglist_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 regionsunmerge_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 contentsearch_table_headers(file_path, query)- Search table headers
🧪 Testing
pytest # Run all tests
pytest --cov=src/docx_mcp # Run with coverage
pytest -v # Verbose output
📄 License
MIT License - see LICENSE file for details.