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

Headers & Footers Configuration (NEW in v0.4.0)

{
  "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

v0.2.0 - Enhanced Document Operations

✅ 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

Install deps

npm install

Dev mode

npm run dev

Build and start

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

{
  "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.

DOCX MCP Server