docx-mcp

A Node.js MCP server that lets clients create, query, edit, and save DOCX documents using a JSON schema, powered by the docx library.

Features

- Complete DOCX operations: Create, edit, and save Word documents via Model Context Protocol (MCP)
- JSON Schema validation: Structured document definition with comprehensive validation
- Rich content blocks:
- Text & Headings: 6 heading levels with advanced formatting
- Lists: Ordered/unordered lists with multiple numbering styles and nesting
- Code Blocks: Syntax highlighting for 180+ languages with themes and line numbers
- Tables: Full table support with styling and cell formatting
- Images: URL downloads with fallback, local files, and base64 embedding
- Page Control: Page breaks and section breaks
- Advanced text formatting:
- Basic: Bold, italic, underline, strikethrough, colors
- Enhanced: Superscript, subscript, font families, highlights, small caps
- Spacing: Character spacing, paragraph alignment, indentation
- Document management: In-memory registry with unique IDs
- Metadata support: Complete document properties and custom metadata
- File operations: Open existing DOCX files and save to disk
- Error handling: Graceful fallbacks and comprehensive validation

JSON Schema

See src/schema.ts for the full schema. Key concepts:
- meta: Document metadata (title, subject, creator, etc.)
- pageSettings: Page size, orientation, margins, header/footer margins (NEW in v0.3.0)
- headers: Page header configuration with default/first/even page support (NEW in v0.4.0)
- footers: Page footer configuration with default/first/even page support (NEW in v0.4.0)
- content: Array of blocks: heading, paragraph, table, image, codeBlock, list, pageBreak, horizontalRule, blockquote, infoBox, textBox
- Enhanced blocks:
- CodeBlock: { type: "codeBlock", language: "javascript", code: "...", showLineNumbers: true }
- List: { type: "list", ordered: true, items: [...] } with nesting support
- Table: Enhanced with backgroundColor, borders, verticalAlign, cell margins (NEW in v0.3.0)
- HorizontalRule: { type: "horizontalRule", style: "single", color: "#666" } (NEW in v0.3.0)
- Blockquote: { type: "blockquote", children: [...], borderColor: "#ccc" } (NEW in v0.3.0)
- InfoBox: { type: "infoBox", boxType: "info", title: "Note", children: [...] } (NEW in v0.3.0)
- TextBox: { type: "textBox", children: [...] } with border styling (NEW in v0.3.0)
- Enhanced TextRun: Supports fontFamily, superScript, subScript, highlight, etc.
- Each paragraph/heading uses inline runs (text, hyperlink) with rich formatting options

$3

``json
{
"headers": {
"default": {
"alignment": "center",
"children": [
{
"type": "documentTitle",
"bold": true,
"size": 14,
"color": "#1f4788"
}
]
},
"first": {
"alignment": "right",
"children": [
{
"type": "text",
"text": "Confidential Document",
"bold": true,
"color": "#cc0000"
}
]
}
},
"footers": {
"default": {
"alignment": "center",
"children": [
{
"type": "text",
"text": "Page "
},
{
"type": "pageNumber",
"format": "decimal"
},
{
"type": "text",
"text": " of "
},
{
"type": "pageNumber",
"format": "totalPages"
}
]
}
}
}
`

Supported header/footer elements:
- text: Static text with styling options
- pageNumber: Auto page numbering (decimal, upperRoman, lowerRoman, upperLetter, lowerLetter)
- currentDate: Auto-updating date with custom format strings
- documentTitle: References document meta.title
- image: Images in headers/footers (base64, path, url)

New in v0.4.0 - Document Structure & Headers/Footers

- ✅ Headers & Footers System: Comprehensive page header and footer support
- Default, first page, and even page headers/footers
- Rich content: text, page numbers, dates, document title, images
- Flexible alignment: left, center, right
- Advanced styling: fonts, colors, sizes, bold/italic
- ✅ Dynamic Content Elements:
- pageNumber: Automatic page numbering with multiple formats (decimal, roman, letters)
- currentDate: Auto-updating dates with custom formats
- documentTitle: Reference document metadata
- text: Static text with full styling options
- image: Headers/footers images support
- ✅ Professional Layout Control:
- Different headers/footers for first page vs. rest of document
- Odd/even page variations for book-style layouts
- Precise margin control for headers and footers
- Integration with existing page settings system

New in v0.3.0 - Styles & Layout

- ✅ Page Settings: Page size (A4, Letter, etc.), orientation, margins control
- ✅ Enhanced Tables: Background colors, border styles, vertical alignment, table templates
- ✅ New Block Types: Horizontal rules, blockquotes, info boxes, text boxes
- ✅ Advanced Styling: More comprehensive table and cell formatting options

Previous Updates

$3

- ✅ Code Blocks: Syntax highlighting for 180+ programming languages
- ✅ Lists: Ordered and unordered lists with multiple styles and nesting
- ✅ Page Breaks: Control document pagination
- ✅ Enhanced Text: Superscript, subscript, font families, highlights
- ✅ Improved Schema: More comprehensive validation and type safety

Run locally

1. Install deps

`pwsh
npm install
`

2. Dev mode

`pwsh
npm run dev
`

3. Build and start

`pwsh
npm run build
npm start
`

Tools

- docx-getSchema { } // Get JSON schema - call this first!
- docx-create { json }
- docx-open { id?, path } // open .docx file from disk
- docx-queryMeta { id }
- docx-queryObjects { id }
- docx-editMeta { id, patch }
- docx-editContent { id, index, block }
- docx-insertContent { id, index, block }
- docx-removeContent { id, index }
- docx-save { id, path }
- docx-exportJson { id }

Example JSON

`json
{
"meta": { "title": "Demo", "creator": "DOCX MCP v0.2.0" },
"content": [
{ "type": "heading", "level": 1, "children": [ { "type": "text", "text": "Title" } ] },
{ "type": "paragraph", "children": [
{ "type": "text", "text": "Hello ", "bold": true },
{ "type": "text", "text": "world", "color": "FF0000" }
]},
{
"type": "codeBlock",
"language": "javascript",
"showLineNumbers": true,
"code": "console.log('Hello, World!');"
},
{
"type": "list",
"ordered": false,
"items": [
{ "children": [{ "type": "text", "text": "First item" }] },
{ "children": [{ "type": "text", "text": "Second item" }] }
]
},
{ "type": "image", "url": "https://picsum.photos/300/200", "width": 300, "height": 200 },
{ "type": "pageBreak" },
{ "type": "table", "rows": [ { "cells": [
{ "children": [ { "type": "paragraph", "children": [ { "type": "text", "text": "A" } ] } ] },
{ "children": [ { "type": "paragraph", "children": [ { "type": "text", "text": "B" } ] } ] }
] } ] }
]
}
`

Image Support

Images can be included in three ways:
- URL: { "type": "image", "url": "https://example.com/image.png", "width": 300, "height": 200 }
- Local file path: { "type": "image", "path": "/path/to/image.png", "width": 300, "height": 200 }
- Base64 data: { "type": "image", "data": "base64string", "format": "png", "width": 150, "height": 100 }`

URL Image Features:
- Automatic download from HTTP/HTTPS URLs
- Fallback to generated placeholder image if download fails
- Placeholder shows original URL and dimensions
- Support for common image formats (PNG, JPEG, JPG)
- Note: Fontconfig warnings on Windows are harmless and can be ignored

Supported formats: PNG, JPEG, JPG

Notes

- Hyperlinks are rendered visually as underlined blue text. Full hyperlink relationships can be added later.
- Images support URL downloads, local file paths, and base64 data.
- This server runs over stdio to be compatible with MCP hosts.