aiexplorations/docx-mcp

docx-mcp: Word Document MCP Server

A comprehensive Model Context Protocol (MCP) server for reading, writing, and manipulating Microsoft Word (.docx) documents. This server provides 30+ tools for complete document lifecycle management, from basic text operations to advanced formatting, templating, and content control.

Features

Phase 1: Core Document Operations

• create_docx - Create new blank documents
• read_docx - Extract text and metadata
• write_docx - Write/overwrite document content
• append_docx - Append content to existing documents
• list_docx - List documents in directory
• delete_docx - Delete documents safely
• copy_docx - Copy documents to new locations

Phase 2: Word Native Template System

• list_merge_fields - Extract MERGEFIELD names from documents
• fill_merge_fields - Replace merge field values with data
• list_content_controls - List all content controls
• get_document_properties - Read document metadata
• set_document_properties - Update document metadata

Phase 3: Style Management

• list_styles - List all available paragraph and character styles
• apply_paragraph_style - Apply named styles ("Heading 1", "Normal", etc.)

Phase 4: Lists - Bullets and Numbering

• apply_bullet_list - Apply bullet formatting
• apply_numbered_list - Apply numbered formatting
• set_list_level - Control list indentation levels (0-8)

Phase 5: Images and Captions

• insert_image - Insert images with sizing options
• add_image_caption - Add auto-numbered captions
• list_images - List all images in document

Additional Features

• Structured JSON logging
• Security-first design with path validation
• Comprehensive error handling
• Support for document properties and metadata
• MCP resource endpoints for document content access

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager (or pip)

Quick Start

# 1. Clone or navigate to the project
cd docx-mcp

# 2. Run setup script
./setup.sh

# 3. Activate virtual environment
source venv/bin/activate

# 4. Run the server
./run.sh

Manual Setup

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
uv sync

# Run server
python -m docx_mcp.server

Usage with Claude

Option 1: Claude Desktop

1. Copy the configuration to Claude:

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Update the path to your docx-mcp installation:

{
  "mcpServers": {
    "docx-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/docx-mcp",
        "run",
        "python",
        "-m",
        "docx_mcp.server"
      ]
    }
  }
}

3. Restart Claude Desktop

Option 2: Programmatic Use

from docx_mcp.server import app

# Access tools programmatically
# Or run via MCP protocol
app.run(transport="stdio")

Example Commands

Creating and Writing Documents

User: Create a new Word document at ./report.docx with the title "Monthly Report"
Tool: create_docx(filepath="./report.docx", title="Monthly Report")

User: Write some content to the document
Tool: write_docx(filepath="./report.docx", content="Executive Summary\nKey Findings...")

Applying Styles and Formatting

User: List available styles in the document
Tool: list_styles(filepath="./report.docx")

User: Apply Heading 1 style to the first paragraph
Tool: apply_paragraph_style(filepath="./report.docx", paragraph_index=0, style_name="Heading 1")

Creating Lists

User: Make paragraphs 3-5 a bulleted list
Tool: apply_bullet_list(filepath="./report.docx", paragraph_indices=[3,4,5])

User: Convert those to a numbered list instead
Tool: apply_numbered_list(filepath="./report.docx", paragraph_indices=[3,4,5])

User: Increase indentation to level 2
Tool: set_list_level(filepath="./report.docx", paragraph_index=3, level=2)

Working with Images

User: Insert this image into the document
Tool: insert_image(filepath="./report.docx", image_path="./logo.png", width=2.5)

User: Add a caption to it
Tool: add_image_caption(filepath="./report.docx", image_index=0, caption_text="Company Logo", caption_type="Figure")

Document Properties

User: Set document metadata
Tool: set_document_properties(
    filepath="./report.docx",
    author="John Doe",
    subject="Monthly Report",
    keywords="report,monthly,2024"
)

User: Get document properties
Tool: get_document_properties(filepath="./report.docx")

Configuration

Environment Variables

# Project directory for document access
export DOCX_MCP_PROJECT_DIR=/path/to/documents

# Maximum file size (default: 50MB)
export DOCX_MCP_MAX_FILE_SIZE=52428800

# Logging level (DEBUG, INFO, WARNING, ERROR)
export DOCX_MCP_LOG_LEVEL=INFO

File System Security

The server validates all file paths to prevent directory traversal attacks:

• Restricts access to configured directories
• Validates file extensions (.docx, .doc, .dotx, .dot)
• Enforces file size limits
• Prevents null byte injection

Logging

Logs are stored in the logs/ directory with both console and file output:

• Console: Human-readable format
• Files: JSON format for log aggregation

Development

Running Tests

# Install dev dependencies
uv sync --all-extras

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=src/docx_mcp

Code Style

# Format code
uv run black src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type check
uv run mypy src/

Project Structure

docx-mcp/
├── src/docx_mcp/
│   ├── __init__.py           # Package initialization
│   ├── server.py             # Main MCP server with all tools
│   ├── config.py             # Configuration management
│   ├── logging_config.py     # Logging setup
│   ├── exceptions.py         # Custom exception classes
│   ├── utils/
│   │   ├── path_utils.py     # Path validation and normalization
│   │   ├── document_utils.py # Document handling utilities
│   │   └── __init__.py
│   ├── tools/                # Tool implementations (future phases)
│   ├── resources/            # MCP resource providers
│   └── __init__.py
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── test_server.py        # Server tests
├── pyproject.toml            # Project metadata and dependencies
├── setup.sh                  # Environment setup script
├── run.sh                    # Server launch script
├── claude_desktop_config.json # Claude configuration example
└── README.md                 # This file

Supported Document Formats

• .docx - Modern Microsoft Word format (recommended)
• .doc - Legacy Microsoft Word format
• .dotx - Word template format
• .dot - Legacy Word template format

Limitations and Future Work

Current Limitations

• Basic merge field handling (without full field code support)
• Simplified image positioning
• No advanced table manipulation
• No document comparison

Planned Enhancements

• Phase 6: Advanced text formatting (fonts, colors, alignment)
• Phase 7: Complete table operations
• Phase 8: Document structure (sections, headers, footers, TOC)
• Phase 9: Document analysis and statistics
• Phase 10: Format conversion (PDF, Markdown, TXT)
• Phase 11: Batch operations
• Phase 12: MCP resource endpoints

Security Considerations

This server is designed for local use. When deploying to production or exposing over a network:

1. Authentication: Implement OAuth2 or JWT token validation
2. Authorization: Restrict file access by scope
3. Rate Limiting: Implement rate limits to prevent abuse
4. Audit Logging: Log all document access and modifications
5. Network Security: Use TLS/SSL for network communication
6. File Validation: Scan documents for malware

Troubleshooting

Virtual Environment Issues

# Recreate virtual environment
rm -rf venv/
./setup.sh

Dependencies Not Installing

# Update pip
source venv/bin/activate
pip install --upgrade pip

# Install with uv
uv sync --upgrade

Server Won't Start

# Check Python version
python3 --version  # Should be 3.10+

# Check logs
cat logs/docx_mcp_*.log

License

MIT

Contributing

Contributions are welcome! Please ensure:

• Code follows PEP-8 style guidelines
• All tests pass
• New features include tests
• Documentation is updated

Support

For issues or questions:

1. Check the logs in logs/ directory
2. Verify file paths are correct
3. Ensure document format is supported
4. Review error messages for guidance

Built with FastMCP and python-docx for comprehensive Word document management.