Docx Editor

Python MCP License python-docx

A powerful Model Context Protocol (MCP) server for creating, editing, and extracting data from Microsoft Word documents (.docx). Designed for seamless integration with AI assistants like Claude Desktop, Kilocode, and other MCP-compatible clients.

📋 Table of Contents

• Features
• Installation
• Configuration
• Available Tools
• Usage Examples
• Technology Stack
• Contributing
• License

✨ Features

Document Creation & Management

• Create new documents with pre-configured professional styles (Times New Roman, 14pt, justified alignment, 1.15 line spacing)
• Load existing templates for modification
• Save documents to any specified path

Content Editing

• Add headings with automatic styling (centered, Times New Roman, 16pt)
• Add paragraphs with customizable alignment (LEFT, CENTER, RIGHT, JUSTIFY)
• Insert formatted text with bold, italic, custom font sizes, and language attributes
• Create bullet and numbered lists with automatic formatting

Document Analysis & Extraction

• Extract all document parameters as structured JSON including:
  • Core properties (author, title, subject, keywords, created/modified dates)
  • Custom properties (user-defined metadata)
  • Document variables (for mail merge and automation)
  • Section properties (margins, page size, orientation)
  • Style definitions (fonts, colors, spacing, indentation)
  • Numbering and list definitions
  • Headers and footers content
  • Table structures

Template Generation

• Apply extracted parameters to create new documents with identical formatting
• Set core properties programmatically (author, title, subject, etc.)
• Set custom properties for document metadata

Document Structure Analysis

• Get comprehensive document structure summaries
• List all headings with levels and text
• Count paragraphs and tables
• Preview document content

📦 Installation

Prerequisites

• Python 3.10 or higher
• pip package manager

Quick Start

1. Clone the repository:

   git clone https://github.com/yourusername/docx-editor-mcp.git
   cd docx-editor-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Verify installation:

   python -c "from docx import Document; from mcp.server.fastmcp import FastMCP; print('Installation successful!')"
   

⚙️ Configuration

Understanding MCP Servers

Important: MCP servers communicate via stdio using JSON-RPC protocol. They are NOT meant to be run directly from the command line for interactive use. Instead, they must be launched by an MCP client.

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "docx-editor": {
      "command": "python",
      "args": ["C:\\path\\to\\docx-editor-mcp\\server.py"]
    }
  }
}

Kilocode / VS Code Configuration

Add to your VS Code settings or Kilocode configuration:

{
  "mcp.servers": {
    "docx-editor": {
      "command": "python",
      "args": ["/path/to/docx-editor-mcp/server.py"]
    }
  }
}

🔧 Available Tools

Document Creation & Management

Tool	Description
create_document(filename)	Creates a new document with default professional styles
save_document(filename)	Saves the current document to specified path
load_template(filename)	Loads an existing document for modification

Content Addition

Tool	Description
add_heading(text, level)	Adds a heading (Level 1-6) with default styling
add_heading_custom(text, level, font_size)	Adds a heading with custom font size
add_paragraph(text, alignment, indent_first_line)	Adds a paragraph with alignment options
add_formatted_text(paragraph_index, text, bold, italic, font_size, lang)	Appends styled text to a paragraph
add_list_item(text, style)	Adds bullet or numbered list item
insert_header_near_text(target_text, header_title, position)	Inserts a header relative to existing text
insert_line_or_paragraph_near_text(target_text, line_text, position)	Inserts a paragraph relative to existing text
insert_numbered_list_near_text(target_text, list_items, position, bullet_type)	Inserts a list relative to existing text
format_text(paragraph_index, start_pos, end_pos, bold, italic...)	Formats a specific character range in a paragraph
search_and_replace(find_text, replace_text)	Replaces text globally across the document
delete_paragraph(paragraph_index)	Deletes a paragraph by index
create_custom_style(style_name, bold, italic, color, font_size...)	Creates a custom paragraph style

Table Manipulation

Tool	Description
add_table(rows, cols, style, alignment)	Creates a new table
add_table_row(table_index)	Adds a new row to a table
add_table_column(table_index, width_pt)	Adds a new column to a table
set_table_cell(table_index, row, col, text, alignment, bold, italic)	Sets cell text and basic formatting
merge_table_cells(table_index, start_row, start_col, end_row, end_col)	Merges a rectangular range of cells
set_table_cell_style(table_index, row, col, shading_color, vertical_alignment)	Sets cell background color and alignment
set_table_borders(table_index, border_size, border_color)	Applies custom borders to a table
delete_table_row(table_index, row_index)	Deletes a specific row
delete_table_column(table_index, col_index)	Deletes a specific column

Parameter Extraction

Tool	Description
extract_document_parameters(filename, compact, all_styles)	Extract ALL document parameters as JSON
extract_core_properties(filename)	Extract metadata (author, title, dates, etc.)
extract_custom_properties(filename)	Extract user-defined custom properties
extract_document_variables(filename)	Extract document variables for automation
extract_section_properties(filename)	Extract margins, page size, orientation
extract_styles_info(filename, all_styles, compact)	Extract style definitions
get_document_structure(filename)	Get headings, paragraphs, tables summary

Template Generation

Tool	Description
apply_template_parameters(parameters_json, output_filename)	Create document from JSON parameters
set_core_property(property_name, value)	Set metadata property
set_custom_property(property_name, value)	Set custom property

📖 Usage Examples

Creating a New Document

Ask your AI assistant:

Create a new Word document called "report.docx" with:
- A heading "Annual Report 2024"
- A paragraph about company performance
- A bullet list with key achievements

The server will execute:

create_document("report.docx")
add_heading("Annual Report 2024", level=1)
add_paragraph("The company has shown remarkable growth this year...")
add_list_item("Revenue increased by 25%", style="List Bullet")
add_list_item("Expanded to 3 new markets", style="List Bullet")
save_document()

Extracting Document Parameters

Extract all parameters from "template.docx" and show me the styles used.

Returns structured JSON:

{
  "core_properties": {
    "author": "John Doe",
    "title": "Company Template",
    "created": "2024-01-15T10:30:00"
  },
  "sections": [{
    "margins": {
      "top_mm": 15,
      "bottom_mm": 15,
      "left_mm": 20,
      "right_mm": 20
    },
    "orientation": "portrait"
  }],
  "styles": {
    "paragraph_styles": {
      "Normal": {
        "font": {"name": "Times New Roman", "size_pt": 14},
        "paragraph_format": {"alignment": "JUSTIFY", "line_spacing": 1.15}
      }
    }
  }
}

Cloning a Document Template

Extract parameters from "template.docx" and create a new document "new_report.docx" with the same formatting.

params = extract_document_parameters("template.docx")
apply_template_parameters(params, "new_report.docx")
# Now add your content...
add_heading("New Report", level=1)
add_paragraph("Your content here...")
save_document()

Analyzing Document Structure

Load "document.docx" and show me its structure.

Returns:

{
  "headings": [
    {"index": 0, "level": "Heading 1", "text": "Introduction"},
    {"index": 5, "level": "Heading 2", "text": "Methodology"}
  ],
  "paragraphs": [
    {"index": 1, "style": "Normal", "text_preview": "This document describes..."},
    {"index": 2, "style": "Normal", "text_preview": "The following sections..."}
  ],
  "tables_count": 2
}

🛠 Technology Stack

Component	Technology
Language	Python 3.10+
Protocol	Model Context Protocol (MCP)
MCP Framework	FastMCP
Document Engine	python-docx
Communication	JSON-RPC over stdio

Dependencies

mcp>=1.0.0
python-docx>=0.8.11

Default Document Styles

New documents are created with professional default styling:

Element	Style
Normal Text	Times New Roman, 14pt, Justified, 1.15 line spacing
Heading 1	Times New Roman, 16pt, Centered, No bold
Heading 2	Times New Roman, 16pt, Centered, No bold
Margins	Top/Bottom: 15mm, Left/Right: 20mm
First Line Indent	12.7mm (1.27 cm)

🤝 Contributing

Contributions are welcome! Here's how you can help:

Getting Started

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/yourusername/docx-editor-mcp.git
   

3. Create a feature branch:

   git checkout -b feature/amazing-feature
   

4. Make your changes and commit:

   git commit -m "Add amazing feature"
   

5. Push to your branch:

   git push origin feature/amazing-feature
   

6. Open a Pull Request

Contribution Guidelines

• Follow PEP 8 style guidelines
• Add docstrings to all new functions
• Update documentation for any new features
• Test your changes thoroughly before submitting

Feature Requests & Bug Reports

• Open an issue for bug reports or feature requests
• Provide detailed descriptions and reproduction steps for bugs
• Include examples for feature requests

📄 License

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

---

Made with ❤️ for the MCP community