Word MCP Server (word-mcp, PyPI: luiccian-word-mcp) is a Python server implementing the Model Context Protocol (MCP) to provide advanced, token-optimized Word document (.docx) creation and editing capabilities for AI assistants (Claude, Cursor, Copilot, Cline).

Designed from the ground up for maximum token efficiency, it replaces chatty micro-iterations with single-pass document construction—saving over 90% of model tokens and conversational turns.

Key Highlights

• ⚡ Single-Pass Document Builder: Create complete, publication-ready documents (headers, footers, page numbers, margins, headings, paragraphs with markdown styling, tables, lists) in 1 single MCP call (word_build_document).
• 📝 Markdown Direct Generation: Instantly turn structured markdown text into professionally styled Word documents (word_create_from_markdown).
• 🎨 Visual Design Presets: Built-in typography and spacing standards (modern, formal, academic, compact).
• 🔍 Lightweight Outline Inspection: Extract heading hierarchies and document stats without dumping full body text (word_get_document_outline), saving context tokens.
• 📦 Batch Content Ingestion: Append multiple sections, tables, and lists to existing documents in a single operation (word_batch_add_content).
• 🔒 Protection & Security: Password protection, editing restrictions, file integrity checks, and PDF conversion.
• 🚀 Zero-Install Execution: Instant launch with uvx luiccian-word-mcp.

Quick Start with uvx (Recommended)

No manual clone or installation required. You can run the server directly using uv:

# Run with stdio transport (default for AI IDEs)
uvx luiccian-word-mcp

# Or run with SSE transport
uvx luiccian-word-mcp --transport sse --host 127.0.0.1 --port 8000

MCP Client Configuration

1. Claude Desktop

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "word-mcp": {
      "command": "uvx",
      "args": ["luiccian-word-mcp"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "/path/to/your/documents"
      }
    }
  }
}

Tip (Local checkout): If running from a local clone:

{
  "mcpServers": {
    "word-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/word-mcp", "word-mcp"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "/path/to/your/documents"
      }
    }
  }
}

2. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "word-mcp": {
      "command": "uvx",
      "args": ["luiccian-word-mcp"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "${workspaceFolder}"
      }
    }
  }
}

Local Development with uv

# 1. Clone repository
git clone https://github.com/LuiccianDev/word-mcp.git
cd word-mcp

# 2. Sync virtual environment and dependencies
uv sync --all-groups

# 3. Run server
uv run word-mcp

# 4. Run tests and linter
uv run pytest
uv run ruff check .

CI/CD & PyPI Trusted Publishing

The repository includes GitHub Actions workflows powered by Astral uv:

• CI (.github/workflows/ci.yml): Runs tests & lint across Python 3.11, 3.12, and 3.13 on Ubuntu. Uses paths-ignore and concurrency cancellation to preserve GitHub Actions minutes.
• Releases (.github/workflows/release.yml): Triggered on v* tags or manually via workflow dispatch. Builds wheel & sdist with uv build, auto-extracts release notes from CHANGELOG.md, and creates a GitHub Release.
• PyPI Publishing (.github/workflows/publish-pypi.yml): Automated PyPI deployment using Trusted Publishing (OIDC) and PEP 740 cryptographic build provenance attestation (actions/attest-build-provenance@v2).

PyPI Trusted Publisher Configuration

To set up or verify Trusted Publishing on PyPI.org:

Token Optimization: Single-Pass vs. Legacy

Visual Design Presets

Modular Skills Ecosystem

The repository provides 3 modular, specialized skills in skills/ for LLMs:

• word-document-creator: Instructs the model to build complete documents in 1 single pass with headers, footers, pagination, tables, and presets.
• word-document-editor: Focuses on lightweight outline inspection, batch mutations, search & replace, and document merging.
• word-document-security: Handles password locking, editing restrictions, and PDF export for distribution.

Project Structure

src/
└── word_mcp/
    ├── core/               # Word document manipulation engines
    │   ├── batch.py        # High-performance single-pass builder & markdown parser
    │   ├── document.py     # Document lifecycle & outline extraction
    │   ├── content.py      # Paragraphs, headings, and lists
    │   ├── tables.py       # Table styling & cell manipulation
    │   └── protection.py   # Password hashing & editing locks
    ├── tools/              # Exposed MCP tools (consolidated)
    │   ├── batch_tools.py  # word_build_document, word_create_from_markdown
    │   ├── document_tools.py # Lifecycle, text, outline, info, PDF
    │   ├── content_tools.py  # Paragraphs, headings, links, bookmarks
    │   ├── format_tools.py   # Styles, headers, footers, page layout
    │   └── protection_tools.py # Protect, unprotect, verify
    ├── models/             # Pydantic response models
    ├── validation/         # Input validators & parameter alias tolerance
    ├── server.py           # FastMCP server registration
    └── __main__.py         # Server entry point

Security

• Restricted Directory Access: Set MCP_ALLOWED_DIRECTORIES to restrict file access to specific folders.
• Path Resolution: Secure path canonicalization prevents path traversal outside allowed directories.
• Non-destructive Defaults: Shims maintain full backward compatibility for existing scripts and configurations.

License

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