Word Automation MCP Server (pywin32 + FastMCP)

A Windows-specific Word document automation MCP server that provides comprehensive Microsoft Word automation capabilities using pywin32 and fastmcp.

Features

Document Management

• ✅ Create new Word documents (with metadata: title, author)
• ✅ Duplicate documents
• ✅ Extract document text and structure
• ✅ View document properties and statistics (pages, words, characters)
• ✅ List available documents in directory
• ✅ Get document outline (heading structure)
• ✅ Convert documents to PDF format
• ✅ Merge multiple documents
• ✅ Compare documents with tracked changes

Content Creation

• ✅ Add headings (levels 1-9, with font, size, bold, italic, bottom border)
• ✅ Insert paragraphs (with style and direct formatting: font, size, bold, italic, colour)
• ✅ Create tables (customisable rows, columns and data)
• ✅ Add images (with width adjustment)
• ✅ Insert page breaks
• ✅ Insert numbered lists
• ✅ Insert bulleted lists
• ✅ Insert content at specific positions (via text search or paragraph index)
• ✅ Search and replace text
• ✅ Add bookmarks for navigation

Rich Text Formatting

• ✅ Format specific text ranges (bold, italic, underline)
• ✅ Change text colour and font properties
• ✅ Create and apply custom styles
• ✅ Delete paragraphs
• ✅ Batch format multiple paragraphs
• ✅ Apply template formatting (professional, academic, report)

Advanced Table Formatting

• ✅ Format table borders and styles (single, double, thick, none)
• ✅ Create unique header row formatting
• ✅ Apply cell shading (RGB colour support)
• ✅ Alternating row colours for readability
• ✅ Enhanced header row highlighting (custom background and text colours)
• ✅ Cell text formatting (bold, italic, underline, colour, font size, font family)
• ✅ Cell merging (rectangular regions, horizontal, vertical)
• ✅ Cell alignment (horizontal and vertical positioning)
• ✅ Set column widths and table width
• ✅ Auto-fit table columns
• ✅ Cell padding control
• ✅ Extract table data

Footnotes and Endnotes Management

• ✅ Add footnotes to specific paragraphs
• ✅ Add footnotes after specific text
• ✅ Add endnotes to document
• ✅ Convert all footnotes to endnotes
• ✅ Customise footnote style (numbering format: 1,2,3 / a,b,c / i,ii,iii, starting number, font)
• ✅ Delete footnotes (by index or search text)

Document Protection

• ✅ Add password protection (read-only protection)
• ✅ Remove password protection
• ✅ Implement restricted editing (allow comments or revisions)
• ✅ Check document protection status

Comment Management

• ✅ Extract all comments (author, date, text)
• ✅ Filter comments by author
• ✅ Get comments for specific paragraphs
• ✅ Add new comments
• ✅ Delete individual comments
• ✅ Delete all comments

Reference and Layout Tools

• ✅ Insert and update Table of Contents (TOC)
• ✅ Insert and update Table of Figures (TOF)
• ✅ Insert and update Table of Tables
• ✅ Add figure captions
• ✅ Add table captions
• ✅ Update all fields
• ✅ Page layout settings (margins, orientation, size)
• ✅ Page headers and footers
• ✅ Page numbering
• ✅ Auto-number headings

Batch Processing and Automation

• ✅ Batch format paragraphs
• ✅ Batch replace text with multiple find/replace operations
• ✅ Batch insert images
• ✅ Apply consistent formatting to all headings of a specific level

Installation

Prerequisites

• Windows operating system
• Python 3.10 or higher
• Microsoft Word (installed, matching Python architecture)
• UV (recommended) or pip

Quick Installation (using UV - Recommended)

# 1. Clone the repository
git clone https://github.com/yihong1120/Word-Automation-MCP.git
cd Word-Automation-MCP

# 2. Copy environment configuration file
Copy-Item .env.example .env

# 3. Start the server (UV will automatically install dependencies)
uv run python src/server.py

Using Installation Script (Recommended)

The provided setup script automatically handles:

• Checking prerequisites
• Setting up virtual environment
• Installing dependencies
• Generating MCP configuration
• Selecting transport method (stdio/SSE/HTTP)

python setup_mcp.py

Basic Installation

# Clone the repository
git clone https://github.com/yihong1120/Word-Automation-MCP.git
cd Word-Automation-MCP

# Create virtual environment (optional)
python -m venv .venv
.venv\Scripts\activate

# Install as editable package
pip install -e .

Installing from PyPI

# Direct installation (available soon)
pip install word-automation-mcp

# Or using uvx (recommended)
uvx word-automation-mcp

Usage

Quick Start

Using UV (Recommended):

# Method 1: Direct execution
uv run python src/server.py

# Method 2: Using installed package
uv run word-automation-mcp

Using Python:

python src/server.py

Default Configuration:

• Transport: streamable-http
• Server address: http://0.0.0.0:9000/mcp
• Stateless HTTP: Enabled

Transport Configuration

The server supports three transport methods:

1. Streamable HTTP (default) - Modern HTTP transport, suitable for web deployment
2. STDIO - Local execution, works with Claude Desktop
3. SSE (Server-Sent Events) - Compatibility transport

Method 1: Using Environment Variables

Create a .env file (refer to .env.example):

# Transport configuration
MCP_TRANSPORT=streamable-http  # or stdio or sse

# HTTP/SSE configuration
MCP_HOST=0.0.0.0
MCP_PORT=9000
MCP_PATH=/mcp
MCP_STATELESS_HTTP=true

# SSE-specific configuration
MCP_SSE_PATH=/sse

# Debug mode
MCP_DEBUG=0
FASTMCP_LOG_LEVEL=INFO

Method 2: Setting Environment Variables Directly

Windows (PowerShell):

$env:MCP_TRANSPORT="streamable-http"
$env:MCP_PORT="9000"
uv run python src/server.py

Windows (CMD):

set MCP_TRANSPORT=streamable-http
set MCP_PORT=9000
python src/server.py

Server Startup Examples

HTTP Transport (Default):

# Using default configuration (port 9000)
uv run python src/server.py

STDIO Transport:

# Modify .env file
MCP_TRANSPORT=stdio

# Start server
uv run python src/server.py

SSE Transport:

# Modify .env file
MCP_TRANSPORT=sse

# Start server
uv run python src/server.py

Configuring Claude Desktop

Edit the Claude Desktop configuration file:

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

Method 1: After Local Installation (Recommended)

Using system-installed package:

{
  "mcpServers": {
    "word-automation-mcp": {
      "command": "word-automation-mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Using virtual environment:

{
  "mcpServers": {
    "word-automation-mcp": {
      "command": "C:\\path\\to\\Word-Automation-MCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\Word-Automation-MCP\\src\\server.py"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\Word-Automation-MCP",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Method 2: Without Installation (Using uvx)

{
  "mcpServers": {
    "word-automation-mcp": {
      "command": "uvx",
      "args": ["--from", "word-automation-mcp", "word-automation-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Method 3: HTTP/SSE Transport (Remote or Containerised Deployment)

Streamable HTTP:

{
  "mcpServers": {
    "word-automation-mcp": {
      "command": "word-automation-mcp",
      "env": {
        "MCP_TRANSPORT": "streamable-http",
        "MCP_HOST": "0.0.0.0",
        "MCP_PORT": "8000",
        "MCP_PATH": "/mcp"
      }
    }
  }
}

SSE (Server-Sent Events):

{
  "mcpServers": {
    "word-automation-mcp": {
      "command": "word-automation-mcp",
      "env": {
        "MCP_TRANSPORT": "sse",
        "MCP_HOST": "0.0.0.0",
        "MCP_PORT": "8000",
        "MCP_SSE_PATH": "/sse"
      }
    }
  }
}

Note: You need to restart Claude Desktop after configuration.

Complete API Reference

Document Operation Tools

# Create and manage documents
create_document(filename, title=None, author=None)
duplicate_document(source_path, target_path)
get_document_info(filename)
get_document_text(filename)
get_document_outline(filename)
get_document_statistics(filename)
list_available_documents(directory=".")
list_paragraph_texts(filename, limit=50)
convert_to_pdf(filename, output_filename=None)
merge_documents(target_path, source_paths, page_break_between=True)
compare_documents(file_path1, file_path2, output_path)
insert_document_at_bookmark(filename, bookmark_name, source_document_path)

Content Creation Tools

# Add content
add_paragraph(filename, text, style=None, font_name=None, font_size=None,
              bold=None, italic=None, color=None)
add_heading(filename, text, level=1, font_name=None, font_size=None,
            bold=None, italic=None, border_bottom=False)
add_table(filename, rows, cols, data=None)
add_picture(filename, image_path, width=None)
add_page_break(filename)

# Lists
insert_numbered_list(filename, items, target_text=None,
                     target_paragraph_index=None, position='after')
insert_bulleted_list(filename, items, target_text=None,
                     target_paragraph_index=None, position='after')

# Text operations
delete_paragraph(filename, paragraph_index)
search_and_replace(filename, find_text, replace_text)
get_paragraph_text(filename, paragraph_index)
find_text_in_document(filename, text_to_find, match_case=True, whole_word=False)

# Bookmarks
add_bookmark(filename, bookmark_name, paragraph_index=None, search_text=None)
list_bookmarks(filename)

Formatting Tools

# Text formatting
format_text(filename, paragraph_index, start_pos, end_pos,
            bold=None, italic=None, underline=None, color=None,
            font_size=None, font_name=None)
format_text_robust(filename, paragraph_index, start_pos, end_pos,
                   bold=None, italic=None, underline=None, color=None,
                   font_size=None, font_name=None)
create_custom_style(filename, style_name, bold=None, italic=None,
                   font_size=None, font_name=None, color=None, base_style=None)

# Table formatting
format_table(filename, table_index, has_header_row=None, border_style=None)
set_table_cell_shading(filename, table_index, row_index, col_index,
                       fill_color, pattern="clear")
apply_table_alternating_rows(filename, table_index, color1="FFFFFF", color2="F2F2F2")
highlight_table_header(filename, table_index, header_color="4472C4", text_color="FFFFFF")
merge_table_cells(filename, table_index, start_row, start_col, end_row, end_col)
merge_table_cells_horizontal(filename, table_index, row_index, start_col, end_col)
merge_table_cells_vertical(filename, table_index, col_index, start_row, end_row)
set_table_cell_alignment(filename, table_index, row_index, col_index,
                         horizontal="left", vertical="top")
format_table_cell_text(filename, table_index, row_index, col_index,
                       text_content=None, bold=None, italic=None, underline=None,
                       color=None, font_size=None, font_name=None)
set_table_column_width(filename, table_index, column_index, width_cm)
set_table_column_widths(filename, table_index, widths_cm)
set_table_width(filename, table_index, width_cm=None, auto_fit=False)
auto_fit_table_columns(filename, table_index)
set_table_cell_padding(filename, table_index, top_cm=0, bottom_cm=0, left_cm=0, right_cm=0)

Batch Processing Tools

batch_format_paragraphs(file_path, paragraph_indices, bold=None, italic=None,
                       font_size=None, font_name=None)
batch_replace_text(file_path, replacements, match_case=False)
apply_style_to_all_headings(file_path, heading_level, font_name=None,
                            font_size=None, bold=None, color=None)
batch_insert_images(file_path, image_paths, position="end", width_cm=None)
apply_template_formatting(file_path, template_name)
extract_all_tables_data(file_path)
auto_number_headings(file_path, start_level=1, end_level=3, number_format="1.1.1")

Footnote and Endnote Tools

add_footnote(filename, paragraph_index, footnote_text)
add_footnote_after_text(filename, search_text, footnote_text)
add_endnote(filename, paragraph_index, endnote_text)
convert_footnotes_to_endnotes(filename)
customize_footnote_style(filename, numbering_format="1, 2, 3", start_number=1,
                        font_name=None, font_size=None)
delete_footnote(filename, footnote_index=None, search_text=None)

Document Protection Tools

protect_document(filename, password)
protect_document_with_password(file_path, password, allow_reading=True, allow_comments=False)
unprotect_document(filename, password)
add_restricted_editing(filename, password=None, allow_comments=False, allow_revisions=False)
check_protection_status(filename)

Comment Management Tools

get_all_comments(filename)
get_comments_by_author(filename, author)
get_comments_for_paragraph(filename, paragraph_index)
add_comment(filename, text, paragraph_index=None, search_text=None)
delete_comment(filename, comment_index)
delete_all_comments(filename)

Figure and Reference Tools

# Figures
insert_figure_with_caption(filename, image_path, caption_text, width_cm=None,
                          position="end", label="Figure")
add_caption_to_figure(filename, image_index, caption_text, label="Figure")
insert_table_of_figures(filename, position="start", caption_label="Figure")

# Tables
add_caption_to_table(filename, table_index, caption_text, position="above", label="Table")
insert_table_of_tables(filename, position="start")

# Table of Contents
insert_table_of_contents(filename, position="start", show_page_numbers=True,
                        right_align_page_numbers=True, heading_levels=3)
create_table_of_contents(file_path, position="start", show_page_numbers=True,
                        right_align_page_numbers=True, heading_levels=3)
update_all_fields(filename)

Layout Tools

# Page setup
set_page_margins(filename, top_cm=2.54, bottom_cm=2.54, left_cm=2.54, right_cm=2.54)
set_margins_robust(filename, top_cm, bottom_cm, left_cm, right_cm)
set_orientation(filename, orientation="portrait")
set_page_size(filename, width_cm=21.0, height_cm=29.7)

# Headers and footers
set_page_header(filename, text, font_name=None, font_size=None, align="left")
set_page_footer(filename, text, font_name=None, font_size=None, align="center")
add_page_numbers(filename, position="bottom", alignment="center", format="1, 2, 3")

Export Tools

export_pdf(filename, output_path=None, open_after=False)
save_as(filename, output_path, file_format="docx")

Robust Tools (Enhanced Error Handling)

create_table_robust(filename, rows, cols, data=None)
insert_paragraph_robust(filename, text, position="end", style=None)
merge_cells_robust(filename, table_index, start_row, start_col, end_row, end_col)

Usage Examples

In Claude Desktop, you can request operations such as:

Document Creation and Basic Operations:

• "Create a new document called 'report.docx' with title '2024 Annual Report' and author 'John Smith'"
• "Duplicate 'template.docx' to 'new_report.docx'"
• "List all Word documents in the documents directory"
• "Convert 'report.docx' to PDF"
• "Merge multiple documents into 'combined.docx'"
• "Compare 'version1.docx' and 'version2.docx' and save the comparison"

Content Addition:

• "Add 'Company Annual Report' as Heading 1 in Helvetica 36pt bold at the top of the document"
• "Add a Heading 2 'Executive Summary' with a bottom border"
• "Add a paragraph in Times New Roman 12pt: 'This report summarises...'"
• "Insert a 3x4 table with the following data: [[Header1, Header2, Header3, Header4], [...]]"
• "Add image 'chart.png' with width of 6 inches"
• "Insert a page break before the conclusion section"

Lists and Advanced Content:

• "Insert a numbered list after the 'Overview' heading: 'Step one: ...', 'Step two: ...', 'Step three: ...'"
• "Add a bulleted list after the paragraph containing 'Key Findings'"
• "Create a bookmark called 'section-1' at the introduction"

Text Formatting:

• "Make the word 'important' in paragraph 5 bold and red"
• "Search and replace all instances of 'old term' with 'new term'"
• "Format the first 20 characters of paragraph 3 as italic blue, font size 14pt"
• "Batch format paragraphs 1, 3, and 5 with Arial 11pt"

Table Formatting:

• "Format table 1 with double borders and the first row as header"
• "Set the background colour of table cell at row 2, column 3 to light blue (E8F4FF)"
• "Apply alternating row colours to table 1 using white and light grey"
• "Highlight table 1 header row with dark blue background and white text"
• "Merge cells from row 1-2, column 1-3 in table 1"
• "Set the text in table row 1, column 2 to bold, font size 14pt, red colour"
• "Auto-fit columns in table 1"
• "Extract data from all tables in the document"

Batch Processing:

• "Apply professional template formatting to the entire document"
• "Auto-number all headings from level 1 to 3 using format '1.1.1'"
• "Batch replace: 'color' with 'colour', 'center' with 'centre', 'analyze' with 'analyse'"
• "Apply consistent formatting to all level 2 headings: Arial 14pt bold blue"

Footnotes and Endnotes:

• "Add a footnote at the end of paragraph 5: 'This is the source of the reference'"
• "Add a footnote after the text 'important statement'"
• "Convert all footnotes to endnotes"
• "Customise footnote style to use Roman numerals, starting from 1"
• "Delete the footnote containing 'outdated reference'"

Document Protection:

• "Protect the document as read-only with password 'secure123'"
• "Check the document's protection status"
• "Add restricted editing to allow only comments with password 'review456'"

Comment Management:

• "Extract all comments from the document"
• "Get all comments by 'John Smith'"
• "Add a comment to paragraph 3: 'Needs further review'"
• "Delete all comments from the document"

References and Layout:

• "Insert a table of contents at the start showing 3 heading levels"
• "Insert a table of figures after the table of contents"
• "Add figure caption 'Figure 1: Sales Chart' to the first image"
• "Set page margins to 2.5cm on all sides"
• "Change page orientation to landscape"
• "Add page numbers at the bottom centre in format '1, 2, 3'"
• "Set header text to 'Annual Report 2024' aligned right"

Configuration

Default configuration in src/config.py:

@dataclass
class WordConfig:
    # Document root directory (relative paths are based on this directory)
    base_dir: Path = Path.cwd() / "documents"

    # Whether to display Word window (set to True for debugging)
    visible: bool = False

    # Whether to open documents in read-only mode by default
    read_only: bool = False

Environment Variables

All configuration can be set via environment variables (see .env.example):

# Transport configuration
MCP_TRANSPORT=streamable-http  # Options: stdio, sse, streamable-http
MCP_HOST=0.0.0.0              # Server host
MCP_PORT=9000                 # Server port
MCP_PATH=/mcp                 # HTTP endpoint path
MCP_STATELESS_HTTP=true       # Enable stateless HTTP mode

# SSE configuration
MCP_SSE_PATH=/sse            # SSE endpoint path

# Debugging
MCP_DEBUG=0                   # Enable debug mode (0 or 1)
FASTMCP_LOG_LEVEL=INFO       # Log level: DEBUG, INFO, WARNING, ERROR

Project Structure

Word-Automation-MCP/
├── src/
│   ├── server.py              # Main server entry point
│   ├── mcp_instance.py        # FastMCP instance
│   ├── config.py              # Configuration management
│   ├── word_client.py         # Word COM client wrapper
│   └── tools/                 # Tool modules directory
│       ├── __init__.py        # Tools package initialisation
│       ├── document_tools.py  # Document management operations
│       ├── content_tools.py   # Content creation and manipulation
│       ├── format_tools.py    # Text and table formatting
│       ├── footnote_tools.py  # Footnote and endnote management
│       ├── protection_tools.py # Document protection features
│       ├── comment_tools.py   # Comment management
│       ├── figure_tools.py    # Image operations
│       ├── reference_tools.py # References and bookmarks
│       ├── layout_tools.py    # Page layout settings
│       ├── export_tools.py    # Export functionality
│       ├── robust_tools.py    # Enhanced error handling tools
│       └── batch_tools.py     # Batch processing tools
├── test_all_mcp_tools.py      # Comprehensive test suite
├── test_simple_functional.py  # Simple functional tests
├── word_automation_mcp.py     # Entry point wrapper
├── pyproject.toml             # Project configuration and dependencies
├── uv.lock                    # UV lock file
├── .env.example               # Environment variable template
├── README.md                  # This documentation
└── LICENSE                    # MIT licence

Testing

The project includes comprehensive test suites to verify all MCP tools are functioning correctly.

Running Tests

# Run comprehensive test suite
python test_all_mcp_tools.py

# Run simple functional test
python test_simple_functional.py

Test Coverage

• 86 MCP tools tested and verified
• Import validation for all 12 tool modules
• Tool registration verification
• Schema validation
• Python syntax checking

All tests pass successfully with no errors.

Troubleshooting

Common Issues

1. Permission Errors

   • Ensure the server has read/write permissions to the document directory
   • Use duplicate_document to create copies of locked documents

2. Word Not Installed

   • This server requires Microsoft Word to be installed
   • Ensure Word is properly registered as a COM object
   • Python and Word architecture must match (both 32-bit or both 64-bit)

3. Import Errors

   • Ensure dependencies are installed: pip install -e . or use uv
   • Check Python version >= 3.10
   • Verify all tool module files exist

4. COM Errors

   • Close all Word processes and retry
   • Check Windows Event Viewer for errors
   • Try running with administrator privileges
   • Ensure pywin32 is properly installed

5. Transport Configuration Issues

   • STDIO: Verify Claude Desktop configuration is correct
   • HTTP/SSE: Check if port is already in use
   • Network: Verify firewall settings allow connections

6. Module Not Found

   • Ensure PYTHONPATH is set correctly
   • Install package in editable mode: pip install -e .
   • Use UV for automatic dependency management

Debug Mode

Enable verbose logging:

Windows (PowerShell):

$env:MCP_DEBUG="1"
$env:FASTMCP_LOG_LEVEL="DEBUG"
uv run python src/server.py

Linux/macOS:

export MCP_DEBUG=1
export FASTMCP_LOG_LEVEL=DEBUG
python src/server.py

Or set in .env file:

MCP_DEBUG=1
FASTMCP_LOG_LEVEL=DEBUG

Documentation

• Quick Start Guide - Get started in 5 minutes
• Deployment Guide - Cloud platform deployment instructions
• API Reference - Complete tool listing
• Configuration Options - Environment variables and settings

Development and Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone repository
git clone https://github.com/yihong1120/Word-Automation-MCP.git
cd Word-Automation-MCP

# Install in development mode
pip install -e .

# Run tests
python test_all_mcp_tools.py

Licence

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

Acknowledgements

• Model Context Protocol - Protocol specification
• FastMCP - Python MCP SDK implementation
• pywin32 - Windows COM interface
• GongRzhe/Office-Word-MCP-Server - Feature reference and inspiration

Important Notes

This server interacts directly with document files on your system. When using with Claude Desktop or other MCP clients, always verify the appropriateness of requests before confirming operations. Recommendations:

• Create backups before operating on important documents
• Use duplicate_document to experiment on copies
• Save work regularly
• Use test documents when testing new features
• Review changes before saving documents
• Be cautious with batch operations on multiple files

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check existing documentation and troubleshooting guide
• Review closed issues for similar problems

Version History

See CHANGELOG.md for version history and release notes.