# py-docx-mcp

Python MCP server for DOCX document manipulation, optimized for OpenWebUI (Streamable HTTP).

## Features

- Full-featured DOCX tools:
  - Create, open, edit, merge, split documents
  - Add paragraphs, headings, tables, lists, images, hyperlinks
  - Find/replace (plain and regex)
  - Template-based document generation
  - Export to Markdown/HTML
  - Metadata, structure, and search utilities
- Transport:
  - OpenWebUI MCP (Streamable HTTP)
- Auth:
  - Optional API key via environment (Bearer or X-API-Key)
- Document delivery:
  - Generated files returned as base64 content to the caller (no external mounts required)

## Quick Start

### Build

- docker build -t py-docx-mcp .

### Run

- docker run --rm -p 3000:3000 py-docx-mcp

### With API key

- docker run --rm -p 3000:3000 -e DOCX_MCP_API_KEY="your-secret-key" py-docx-mcp

### Connect in OpenWebUI

- Admin Settings → External Tools → + Add Server
- Type: MCP (Streamable HTTP)
- URL: http://<host>:3000
- Auth:
  - If DOCX_MCP_API_KEY is set: Bearer with your key
  - Otherwise: None

## Environment

- DOCX_MCP_API_KEY: API key (optional but recommended)
- DOCX_MCP_HTTP_HOST: Bind host (default: 0.0.0.0)
- DOCX_MCP_HTTP_PORT: Bind port (default: 3000)
- DOCX_MCP_TEMPLATES_DIR: Templates directory (default: /templates)
- DOCX_MCP_MAX_SIZE: Max document size in bytes (default: 104857600)
- DOCX_MCP_MAX_DOCS: Max open documents (default: 30)
- DOCX_MCP_SANDBOX: Enable sandbox mode (default: true)
- DOCX_MCP_ALLOW_EXTERNAL_TOOLS: Allow external tools (default: false)
- DOCX_MCP_ALLOW_NETWORK: Allow network access (default: false)