# Docx Mcp

> MCP Server for dealing with Microsoft .docx files

- **Type:** MCP server
- **Install:** `agentstack add mcp-hongkongkiwi-docx-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hongkongkiwi](https://agentstack.voostack.com/s/hongkongkiwi)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hongkongkiwi](https://github.com/hongkongkiwi)
- **Source:** https://github.com/hongkongkiwi/docx-mcp

## Install

```sh
agentstack add mcp-hongkongkiwi-docx-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# DOCX MCP Server

A comprehensive Model Context Protocol (MCP) server for Microsoft Word DOCX file manipulation, built with Rust. This server provides AI systems with powerful tools to create, edit, convert, and manage Word documents programmatically.

## 📖 Table of Contents

- [Quick Start](#-quick-start)
- [AI Tool Integration](#-ai-tool-integration)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf-codeium)
  - [Continue.dev](#continuedev)
  - [VS Code](#vs-code-with-mcp-extension)
- [Features](#-features)
- [Real-World Usage Examples](#-real-world-usage-examples-with-ai-assistants)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Common Use Cases](#-common-use-cases)
- [Available Tools](#available-tools)
- [Example Workflows](#example-workflows)
- [Architecture](#architecture)
- [Development](#development)
- [Troubleshooting](#-troubleshooting)
- [Examples Directory](#-examples-directory)
- [Contributing](#contributing)
- [License](#license)

## 🚀 Quick Start

```bash
# Clone the repository
git clone https://github.com/yourusername/docx-mcp.git
cd docx-mcp

# Download embedded fonts for standalone operation (optional but recommended)
./download_fonts.sh

# Build the server (creates a fully standalone binary)
./build.sh

# The server is now ready - no external dependencies required!
```

### 🎯 Standalone Operation

This MCP server is designed to work **completely standalone** without requiring LibreOffice, unoconv, or any external tools:

- ✅ **Pure Rust DOCX parsing** - No external libraries needed
- ✅ **Built-in PDF generation** - Creates PDFs without LibreOffice
- ✅ **Embedded fonts** - Professional typography included in the binary
- ✅ **Native image processing** - PNG/JPG generation without ImageMagick
- ✅ **Zero external dependencies** - Single binary deployment

The server will automatically use external tools if available for enhanced quality, but they are **completely optional**.

## 🔒 Security Features

The server includes comprehensive security features for enterprise and restricted environments:

### Readonly Mode
```bash
# Enable readonly mode - only allows document viewing and analysis

# Using environment variables
export DOCX_MCP_READONLY=true
./target/release/docx-mcp

# Using command line arguments
./target/release/docx-mcp --readonly
```

In readonly mode, only these operations are allowed:
- Open and view documents
- Extract text and analyze structure
- Export to other formats (Markdown, PDF)
- Search and word count analysis
- Get document metadata and statistics

### Command Filtering
```bash
# Whitelist specific commands only

# Using environment variables
export DOCX_MCP_WHITELIST="open_document,extract_text,get_metadata,export_to_markdown"

# Using command line arguments
./target/release/docx-mcp --whitelist open_document,extract_text,get_metadata,export_to_markdown

# Or blacklist dangerous commands

# Using environment variables
export DOCX_MCP_BLACKLIST="save_document,convert_to_pdf,merge_documents"

# Using command line arguments
./target/release/docx-mcp --blacklist save_document,convert_to_pdf,merge_documents
```

### Sandbox Mode
```bash
# Restrict all file operations to temp directory only

# Using environment variables
export DOCX_MCP_SANDBOX=true
./target/release/docx-mcp

# Using command line arguments
./target/release/docx-mcp --sandbox
```

### Resource Limits
```bash
# Set maximum document size (100MB default)

# Using environment variables
export DOCX_MCP_MAX_SIZE=52428800  # 50MB
export DOCX_MCP_MAX_DOCS=20
export DOCX_MCP_NO_EXTERNAL_TOOLS=true
export DOCX_MCP_NO_NETWORK=true
./target/release/docx-mcp

# Using command line arguments
./target/release/docx-mcp \
  --max-size 52428800 \
  --max-docs 20 \
  --no-external-tools \
  --no-network
```

## 🤖 AI Tool Integration

### Claude Desktop

Add to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

**With Security Options (using command-line arguments):**
```json
{
  "mcpServers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": ["--readonly", "--max-size", "52428800", "--no-network"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

**With Security Options (using environment variables):**
```json
{
  "mcpServers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info",
        "DOCX_MCP_READONLY": "true",
        "DOCX_MCP_MAX_SIZE": "52428800",
        "DOCX_MCP_NO_NETWORK": "true"
      }
    }
  }
}
```

After adding, restart Claude Desktop. You can then ask Claude to:
- "Create a new Word document with our Q4 report"
- "Convert this DOCX file to PDF"
- "Extract all text from my Word documents"
- "Add a table with sales data to the document"

### Cursor

Add to your Cursor settings (`~/.cursor/config.json` or through Settings UI):

**Basic Configuration:**
```json
{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": [],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}
```

**With Security Options (using command-line arguments):**
```json
{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": ["--sandbox", "--whitelist", "open_document,extract_text,export_to_markdown"],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}
```

**With Security Options (using environment variables):**
```json
{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": [],
        "env": {
          "RUST_LOG": "info",
          "DOCX_MCP_SANDBOX": "true",
          "DOCX_MCP_WHITELIST": "open_document,extract_text,export_to_markdown"
        }
      }
    }
  }
}
```

### Windsurf (Codeium)

Add to your Windsurf configuration (`~/.windsurf/config.json`):

**Basic Configuration:**
```json
{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": [],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}
```

**With Security Options (using arguments):**
```json
{
  "mcp": {
    "servers": {
      "docx": {
        "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
        "args": ["--readonly", "--no-external-tools"],
        "env": {
          "RUST_LOG": "info"
        }
      }
    }
  }
}
```

### Continue.dev

Add to your Continue configuration (`~/.continue/config.json`):

**Basic Configuration:**
```json
{
  "models": [
    {
      "title": "Your Model",
      "provider": "your-provider",
      "mcp_servers": {
        "docx": {
          "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
          "args": []
        }
      }
    }
  ]
}
```

**With Security Options:**
```json
{
  "models": [
    {
      "title": "Your Model",
      "provider": "your-provider",
      "mcp_servers": {
        "docx": {
          "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
          "args": ["--sandbox", "--max-size", "10485760"]
        }
      }
    }
  ]
}
```

### VS Code with MCP Extension

If using the MCP extension for VS Code, add to your workspace settings (`.vscode/settings.json`):

**Basic Configuration:**
```json
{
  "mcp.servers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

**With Security Options:**
```json
{
  "mcp.servers": {
    "docx": {
      "command": "/absolute/path/to/docx-mcp/target/release/docx-mcp",
      "args": ["--readonly", "--blacklist", "save_document,merge_documents"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

## 🔧 Command Line Arguments

The DOCX MCP server supports the following command-line arguments for configuration:

```bash
docx-mcp --help
```

### Available Arguments

| Argument | Environment Variable | Description | Example |
|----------|---------------------|-------------|---------|
| `--readonly` | `DOCX_MCP_READONLY=true` | Enable readonly mode - only viewing operations | `--readonly` |
| `--whitelist ` | `DOCX_MCP_WHITELIST` | Comma-separated list of allowed commands | `--whitelist open_document,extract_text` |
| `--blacklist ` | `DOCX_MCP_BLACKLIST` | Comma-separated list of forbidden commands | `--blacklist save_document,convert_to_pdf` |
| `--sandbox` | `DOCX_MCP_SANDBOX=true` | Restrict file operations to temp directory only | `--sandbox` |
| `--no-external-tools` | `DOCX_MCP_NO_EXTERNAL_TOOLS=true` | Disable external tools (LibreOffice, etc.) | `--no-external-tools` |
| `--no-network` | `DOCX_MCP_NO_NETWORK=true` | Disable network operations | `--no-network` |
| `--max-size ` | `DOCX_MCP_MAX_SIZE` | Maximum document size in bytes | `--max-size 52428800` |
| `--max-docs ` | `DOCX_MCP_MAX_DOCS` | Maximum number of open documents | `--max-docs 20` |
| `--help` | - | Show help information | `--help` |
| `--version` | - | Show version information | `--version` |

### Example Usage

```bash
# Basic usage
./target/release/docx-mcp

# Readonly mode with size limit
./target/release/docx-mcp --readonly --max-size 10485760

# Sandbox mode with command whitelist
./target/release/docx-mcp --sandbox --whitelist open_document,extract_text,export_to_markdown

# Multiple security options
./target/release/docx-mcp \
  --readonly \
  --no-external-tools \
  --no-network \
  --max-size 52428800 \
  --max-docs 10
```

**Note:** Command-line arguments take precedence over environment variables when both are specified.

## 📚 Features

### Document Operations
- **Create & Open**: Create new documents or open existing DOCX files
- **Text Manipulation**: Add paragraphs, headings, lists with full styling support
- **Tables**: Create and format tables with custom layouts
- **Page Layout**: Add page breaks, set headers/footers
- **Find & Replace**: Search and replace text throughout documents
- **Text Extraction**: Extract plain text content from documents

### Conversion Capabilities
- **DOCX to PDF**: Convert Word documents to PDF format
  - Uses LibreOffice/unoconv for high-fidelity conversion
  - Fallback to basic PDF generation if external tools unavailable
- **DOCX to Images**: Convert document pages to PNG/JPG images
  - Configurable DPI for quality control
  - Support for multiple image formats
- **PDF Operations**: Split, merge, and manipulate PDF files

### Advanced Features
- **Document Metadata**: Track creation time, size, author, etc.
- **Styling Support**: Font family, size, bold, italic, underline, colors, alignment
- **Multiple Documents**: Handle multiple documents simultaneously
- **Temp File Management**: Automatic cleanup of temporary files

### Professional Templates
- **Business Letters**: Professional correspondence with proper formatting
- **Resumes**: Modern resume layouts with sections for experience, education, skills
- **Reports**: Technical and business reports with table of contents
- **Invoices**: Professional invoice templates with itemized billing
- **Contracts**: Legal document templates with signature blocks
- **Memos**: Corporate memorandum format
- **Newsletters**: Multi-column layouts for publications

### Advanced Document Features
- **Table of Contents**: Automatic TOC generation with heading links
- **Images & Charts**: Embed images and create data visualizations
- **Hyperlinks & Bookmarks**: Internal and external linking with navigation
- **Footnotes & Endnotes**: Academic and professional citation support
- **Comments & Track Changes**: Collaboration features for document review
- **Watermarks**: Confidential, draft, and custom watermarks
- **Mail Merge**: Automated personalized document generation
- **Custom Styles**: Create and apply consistent formatting themes

### Analysis & Review Tools
- **Document Structure Analysis**: Outline view of headings and sections
- **Formatting Analysis**: Detect fonts, styles, and formatting inconsistencies
- **Advanced Search**: Pattern matching with context and positioning
- **Word Count Statistics**: Detailed metrics including reading time
- **Export Options**: Convert to Markdown, HTML, and other formats

## 💬 Real-World Usage Examples with AI Assistants

### With Claude Desktop

Once configured, you can have natural conversations with Claude:

```
You: "Create a professional invoice template for my consulting business"

Claude will:
1. Create a new DOCX document
2. Add your company header
3. Insert a table for line items
4. Add payment terms and footer
5. Save it as invoice_template.docx
```

```
You: "Convert all the Word documents in my reports folder to PDF"

Claude will:
1. List all DOCX files
2. Open each document
3. Convert to PDF with the same name
4. Report completion status
```

### With Cursor/Windsurf

While coding, you can generate documentation:

```
You: "Generate API documentation from these TypeScript interfaces and save as Word"

The AI will:
1. Parse your code
2. Create a formatted DOCX with:
   - Title and table of contents
   - Endpoint descriptions
   - Request/response examples
   - Error codes table
3. Convert to PDF for distribution
```

### Automation Examples

```python
# Ask your AI: "Create a script to generate monthly reports"
# The AI can use the DOCX server to:

async def generate_monthly_report(month, year):
    # Create document
    doc = await mcp.call("create_document")
    
    # Add dynamic content
    await mcp.call("add_heading", {
        "document_id": doc.id,
        "text": f"Monthly Report - {month} {year}",
        "level": 1
    })
    
    # Add data from your database
    sales_data = fetch_sales_data(month, year)
    await mcp.call("add_table", {
        "document_id": doc.id,
        "rows": format_sales_table(sales_data)
    })
    
    # Convert to PDF and email
    await mcp.call("convert_to_pdf", {
        "document_id": doc.id,
        "output_path": f"reports/{year}_{month}_report.pdf"
    })
```

## 📋 Prerequisites

### Required
- Rust 1.70+ and Cargo (for building from source)
- MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.)

### Completely Optional (for enhanced features)

The server works standalone, but can optionally use these tools if available:
- **LibreOffice** (recommended): For high-quality DOCX to PDF conversion
  ```bash
  # macOS
  brew install libreoffice
  
  # Ubuntu/Debian
  sudo apt-get install libreoffice
  
  # Windows
  # Download from https://www.libreoffice.org/
  ```

- **PDF to Image Tools** (any one of these):
  - pdftoppm (part of poppler-utils)
  - ImageMagick
  - Ghostscript

  ```bash
  # macOS
  brew install poppler imagemagick ghostscript
  
  # Ubuntu/Debian
  sudo apt-get install poppler-utils imagemagick ghostscript
  ```

## 🔧 Installation

### Method 1: Build from Source

```bash
# Clone the repository
git clone https://github.com/yourusername/docx-mcp.git
cd docx-mcp

# Build the server (uses the build script)
./build.sh

# Or manually with cargo
cargo build --release

# Optional: Enable Chrome-based PDF conversion
cargo build --release --features chrome-pdf
```

### Method 2: Download Pre-built Binary (Coming Soon)

```bash
# Download the latest release
curl -L https://github.com/yourusername/docx-mcp/releases/latest/download/docx-mcp-linux-x64 -o docx-mcp
chmod +x docx-mcp
```

### Verify Installation

```bash
# Test the server
./target/release/docx-mcp --version

# Check for optional dep

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hongkongkiwi](https://github.com/hongkongkiwi)
- **Source:** [hongkongkiwi/docx-mcp](https://github.com/hongkongkiwi/docx-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hongkongkiwi-docx-mcp
- Seller: https://agentstack.voostack.com/s/hongkongkiwi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.