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

Related MCP server: MCP Server Office

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.