Rookie0x80/docx-table-mcp

Word Table MCP Server

A Model Context Protocol (MCP) server for performing table operations on Microsoft Word documents using the python-docx library. Built with FastMCP for modern, type-safe MCP server development.

Features

Phase 1 - Core Functionality (Current)

• Document Management

  • Open/create Word documents
  • Save documents
  • Get document information

• Table Structure Operations

  • Create tables with optional headers
  • Delete tables
  • Add/remove rows and columns

• Data Operations

  • Set/get individual cell values
  • Get entire table data in multiple formats (array, object, CSV)
  • List all tables in document

Installation

1. Clone the repository:

git clone <repository-url>
cd docx_table

2. Install dependencies:

pip install -r requirements.txt

3. Install the package in development mode:

pip install -e .

Usage

As MCP Server

Run the MCP server with default STDIO transport:

docx-table-mcp

Or run directly:

python -m docx_table_mcp.server

Transport Protocols

The server supports multiple transport protocols:

STDIO (default) - Standard input/output for direct integration:

docx-table-mcp --transport stdio

SSE (Server-Sent Events) - HTTP-based streaming:

docx-table-mcp --transport sse --host localhost --port 8000

Streamable HTTP - HTTP with streaming support:

docx-table-mcp --transport streamable-http --host localhost --port 8000

Command Line Options

docx-table-mcp --help

Available options:

• --transport {stdio,sse,streamable-http} - Transport protocol (default: stdio)
• --host HOST - Host to bind to for HTTP/SSE transports (default: localhost)
• --port PORT - Port to bind to for HTTP/SSE transports (default: 8000)
• --no-banner - Disable startup banner

Direct Usage

from docx_table_mcp.tools.document_manager import DocumentManager
from docx_table_mcp.tools.table_operations import TableOperations

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

# Open document
result = doc_manager.open_document("document.docx", create_if_not_exists=True)

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

# Set cell value
result = table_ops.set_cell_value("document.docx", 0, 1, 0, "Alice")

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

# Save document
result = doc_manager.save_document("document.docx")

Available MCP Tools

All tools accept JSON parameters and return JSON responses, making them compatible with language models.

Document Operations

• open_document(file_path, create_if_not_exists=True) - Open or create a Word document
• save_document(file_path, save_as=None) - Save a Word document
• get_document_info(file_path) - Get document information

Table Structure Operations

• create_table(file_path, rows, cols, position="end", paragraph_index=None, headers=None) - Create a new table
• delete_table(file_path, table_index) - Delete a table
• add_table_rows(file_path, table_index, count=1, position="end", row_index=None) - Add rows to a table
• add_table_columns(file_path, table_index, count=1, position="end", column_index=None) - Add columns to a table
• delete_table_rows(file_path, table_index, row_indices) - Delete rows from a table

Data Operations

• set_cell_value(file_path, table_index, row_index, column_index, value) - Set individual cell value
• get_cell_value(file_path, table_index, row_index, column_index) - Get individual cell value
• get_table_data(file_path, table_index, include_headers=True, format="array") - Get entire table data

Query Operations

• list_tables(file_path, include_summary=True) - List all tables in document

Example Language Model Usage

Language models can call these tools with JSON parameters:

{
  "tool": "create_table",
  "parameters": {
    "file_path": "document.docx",
    "rows": 3,
    "cols": 4,
    "headers": ["Name", "Age", "City", "Job"]
  }
}

{
  "tool": "set_cell_value",
  "parameters": {
    "file_path": "document.docx",
    "table_index": 0,
    "row_index": 1,
    "column_index": 0,
    "value": "Alice"
  }
}

Examples

See examples/basic_usage.py for a comprehensive example of how to use the library.

Testing

The project uses pytest for testing. Run all tests:

pytest

Run tests with coverage:

pytest --cov=src/docx_table_mcp

Run specific test categories:

pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only
pytest tests/test_document_operations.py  # Specific test file

Run tests with verbose output:

pytest -v

Development Roadmap

Phase 1: Core Functionality ✅

• Basic document operations
• Table CRUD operations
• Single cell data operations

Phase 2: Advanced Features (Planned)

• Table styling and formatting
• Data search and query
• CSV import/export
• Row/column data operations

Phase 3: Extended Features (Planned)

• Table templates
• Batch operations
• Performance optimizations

Phase 4: Enterprise Features (Planned)

• Audit logging

Error Handling

The library includes comprehensive error handling with custom exceptions:

• DocumentNotFoundError - Document file not found
• TableNotFoundError - Table not found in document
• InvalidTableIndexError - Invalid table index
• InvalidCellPositionError - Invalid cell position
• TableOperationError - Table operation failed
• DataFormatError - Invalid data format

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run tests to ensure everything passes
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Requirements

• Python 3.8+
• python-docx>=1.1.0
• fastmcp>=0.4.0