Model Context Protocol (MCP) server for DOCX document operations with comprehensive image support
npm install @docx-mcp/docx-mcpdocx library.
src/schema.ts for the full schema. Key concepts:
{ type: "codeBlock", language: "javascript", code: "...", showLineNumbers: true }
{ type: "list", ordered: true, items: [...] } with nesting support
{ type: "horizontalRule", style: "single", color: "#666" } (NEW in v0.3.0)
{ type: "blockquote", children: [...], borderColor: "#ccc" } (NEW in v0.3.0)
{ type: "infoBox", boxType: "info", title: "Note", children: [...] } (NEW in v0.3.0)
{ type: "textBox", children: [...] } with border styling (NEW in v0.3.0)
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 }`