docx-creator-mcp

A Model Context Protocol (MCP) server for creating, analyzing, and rendering professional Microsoft Word (DOCX) documents. Built on FastMCP and python-docx.

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Quick Start
• MCP Client Configuration
• Tools Reference
  • create_document
  • analyze_document
  • render_document_screenshots
• Block Types
• Inline Styling
• Document Style Overrides
• Examples
• License

---

Overview

docx-creator-mcp exposes three MCP tools that allow AI agents and automation pipelines to generate, inspect, and render Word documents without manual intervention. It accepts structured JSON block data and produces fully formatted .docx files with support for headings, paragraphs, tables, images, lists, quotes, and inline styling.

---

Features

• Document creation from structured block data (headings, paragraphs, tables, images, lists, quotes, page breaks, horizontal rules).
• Inline rich-text styling via <style> tags with support for color, font size, font family, bold, italic, underline, and highlight.
• Document analysis that extracts page layout, metadata, paragraph-level formatting, table structure (including merged cells, nested tables, column spans), inline images, and a global style palette.
• Page rendering to PNG images via LibreOffice headless, Word COM (Windows), or a pure-Python fallback.
• Image embedding from local file paths or URLs.
• Customizable document themes including fonts, colors, margins, and line spacing.

---

Requirements

• Python 3.10 or later
• For PNG rendering (optional): LibreOffice installed, or pdf2image with Poppler

---

Installation

From PyPI

pip install docx-creator-mcp

With PDF rendering support

pip install docx-creator-mcp[pdf]

From source

git clone https://github.com/harmandatta/docx-creator-mcp.git
cd docx-creator-mcp
pip install -e .

---

Quick Start

Run the MCP server:

docx-creator-mcp

Or run as a Python module:

python -m docx_creator_mcp.server

---

MCP Client Configuration

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "docx-creator": {
      "command": "docx-creator-mcp",
      "args": []
    }
  }
}

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "docx-creator": {
      "command": "docx-creator-mcp",
      "args": []
    }
  }
}

Using uvx (no install required)

{
  "mcpServers": {
    "docx-creator": {
      "command": "uvx",
      "args": ["docx-creator-mcp"]
    }
  }
}

---

Tools Reference

create_document

Creates a DOCX file from an ordered list of content blocks.

Parameters:

Parameter	Type	Required	Description
blocks	list[dict]	Yes	Ordered list of content blocks. Each block must include a type field.
output_dir	str	Yes	Directory where the file will be saved. A generated-docx subdirectory is created automatically.
filename	str	No	Output filename. Defaults to document.docx.
document_style	dict	No	Style overrides for fonts, colors, margins, and spacing.
metadata	dict	No	Document metadata: title, author, subject.

Returns: Absolute path to the generated DOCX file.

---

analyze_document

Extracts the complete structure and styling from an existing DOCX file.

Parameters:

Parameter	Type	Required	Description
docx_path	str	Yes	Absolute path to the DOCX file.

Returns: JSON string containing:

• page_layout -- Page dimensions, margins, orientation.
• metadata -- Title, author, creation/modification dates.
• global_palette -- Most-used colors, fonts, and font sizes.
• content -- Ordered list of paragraphs and tables with full run-level formatting.
• styles_defined -- All document-level styles with their properties.

---

render_document_screenshots

Renders DOCX pages as PNG images for visual inspection.

Parameters:

Parameter	Type	Required	Description
docx_path	str	Yes	Absolute path to the DOCX file.
output_dir	str	No	Directory to save PNGs. Defaults to a screenshots folder next to the file.
width	int	No	Output image width in pixels. Defaults to 1600.

Returns: JSON with a list of rendered pages, each containing page, image_path, and backend.

Rendering backends (tried in order):

1. LibreOffice headless (macOS, Linux, Windows)
2. Word COM automation (Windows only)
3. Pure-Python fallback using Pillow

---

Block Types

Each block in the blocks list must include a type field. The following types are supported:

heading

Section heading with configurable level.

{ "type": "heading", "text": "Quarterly Report", "level": 1 }

Field	Type	Default	Description
text	str	--	Heading text. Supports inline <style> tags.
level	int	1	Heading level, 1 through 4.

paragraph

Body text with optional alignment.

{ "type": "paragraph", "text": "Revenue increased by 12%.", "alignment": "justify" }

Field	Type	Default	Description
text	str	--	Paragraph text. Supports inline <style> tags.
alignment	str	"left"	One of left, center, right, justify.

bullet_list

Bulleted list.

{ "type": "bullet_list", "items": ["First item", "Second item", "Third item"] }

Field	Type	Description
items	list[str]	List of bullet items. Each supports <style> tags.

numbered_list

Numbered list.

{ "type": "numbered_list", "items": ["Step one", "Step two", "Step three"] }

Field	Type	Description
items	list[str]	List of numbered items. Each supports <style> tags.

table

Data table with optional header styling and row striping.

{
  "type": "table",
  "headers": ["Name", "Department", "Salary"],
  "rows": [
    ["Alice", "Engineering", "120000"],
    ["Bob", "Marketing", "95000"]
  ],
  "stripe_rows": true
}

Field	Type	Default	Description
headers	list[str]	--	Column header labels.
rows	list[list]	--	Row data. Each inner list is one row.
header_bg_color	str	Accent color	Hex color for the header row background.
stripe_rows	bool	true	Alternate row shading for readability.

image

Inline image from a local path or URL.

{
  "type": "image",
  "image_path": "/path/to/screenshot.png",
  "width_inches": 5.5,
  "caption": "Figure 1: Application dashboard"
}

Field	Type	Default	Description
image_path	str	--	Local file path or HTTP/HTTPS URL.
width_inches	float	5.5	Display width in inches.
caption	str	--	Optional caption rendered below the image.

quote

Block quote with attribution.

{
  "type": "quote",
  "text": "Simplicity is the ultimate sophistication.",
  "attribution": "-- Leonardo da Vinci"
}

Field	Type	Description
text	str	Quote text. Supports inline <style> tags.
attribution	str	Source attribution rendered below the quote.

page_break

Forces a new page.

{ "type": "page_break" }

horizontal_rule

Inserts a horizontal divider line.

{ "type": "horizontal_rule" }

---

Inline Styling

Any text field in any block type supports inline <style> tags for granular formatting control.

Syntax:

Regular text <style color="green" bold="true" text-size="14">highlighted text</style> more text.

Supported attributes:

Attribute	Type	Description
color	str	CSS color name (red, green, blue, orange, accent, muted) or hex (#FF5733).
text-size	number	Font size in points.
font-type	str	Font family name (e.g., Arial, Calibri).
bold	bool	true or false.
italic	bool	true or false.
underline	bool	true or false.
highlight	str	Highlight color: yellow, green, cyan, pink, red, blue, gray.

Named colors:

white, black, red, green, blue, orange, yellow, purple, cyan, gray, darkgray, navy, accent, muted

---

Document Style Overrides

Pass a document_style dictionary to create_document to override the default theme.

Key	Type	Default	Description
font_body	str	Calibri	Body text font family.
font_heading	str	Calibri	Heading font family.
font_size_body	int	11	Body font size in points.
font_size_h1	int	24	Heading 1 font size.
font_size_h2	int	18	Heading 2 font size.
font_size_h3	int	14	Heading 3 font size.
font_size_h4	int	12	Heading 4 font size.
color_body	str	333333	Body text color (hex).
color_heading	str	1A1A2E	Heading color (hex).
color_accent	str	4F81BD	Accent color for tables (hex).
line_spacing	float	1.15	Line spacing multiplier.
page_margin_inches	float	1.0	Page margins in inches.

---

Examples

Minimal document

{
  "blocks": [
    { "type": "heading", "text": "Meeting Notes", "level": 1 },
    { "type": "paragraph", "text": "Discussed Q2 targets and resource allocation." },
    { "type": "bullet_list", "items": ["Hire two engineers", "Finalize budget", "Launch beta"] }
  ],
  "output_dir": "/tmp",
  "filename": "meeting_notes.docx"
}

Report with table and image

{
  "blocks": [
    { "type": "heading", "text": "Sales Report", "level": 1 },
    {
      "type": "table",
      "headers": ["Region", "Q1", "Q2", "Q3"],
      "rows": [
        ["North", "1.2M", "1.4M", "1.5M"],
        ["South", "0.9M", "1.1M", "1.3M"]
      ]
    },
    {
      "type": "image",
      "image_path": "/path/to/chart.png",
      "width_inches": 6,
      "caption": "Figure 1: Quarterly revenue by region"
    },
    {
      "type": "paragraph",
      "text": "Total revenue grew <style color=\"green\" bold=\"true\">18%</style> year-over-year."
    }
  ],
  "output_dir": "/tmp",
  "filename": "sales_report.docx",
  "metadata": { "title": "Q3 Sales Report", "author": "Finance Team" }
}

Custom styling

{
  "blocks": [
    { "type": "heading", "text": "Brand Guidelines", "level": 1 },
    { "type": "paragraph", "text": "All documents must use the corporate font and color scheme." }
  ],
  "output_dir": "/tmp",
  "document_style": {
    "font_body": "Georgia",
    "font_heading": "Georgia",
    "color_accent": "2E86AB",
    "page_margin_inches": 1.25
  }
}

---

License

This project is licensed under the MIT License. See LICENSE for details.