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

1. Install deps

npm install

2. Dev mode

npm run dev

3. 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.