mcp-server-docx

jamesmehorter/mcp-server-docx

3.2

If you are the rightful owner of mcp-server-docx and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Model Context Protocol (MCP) server is a specialized server designed to facilitate communication and data exchange between machine learning models and various client applications.

Word Document MCP Server

A fast, TypeScript-based MCP server for creating professional Word documents from markdown or structured content.

🚀 Markdown-First Workflow - Just write natural markdown and get professional Word documents in ~300ms!

Quick Setup

  1. Download index.js from and save to ~/mcp-servers/docx/index.js

  2. Configure Claude Desktop - edit claude_desktop_config.json:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    {
  "mcpServers": {
    "mcp-server-docx": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/mcp-servers/docx/index.js"]
    }
  }
}

    Replace the path with where you saved the file (Windows: use C:\\Users\\... with double backslashes)

  3. Restart Claude Desktop

  4. Test by asking Claude:

Create a Word document at /tmp/test.docx from this markdown:

# Hello World

This is my **first** Word document with *markdown*!

## Features
- Easy to use
- Fast generation
- Professional formatting

You should get a properly formatted Word document at /tmp/test.docx!

Build from Source (for contributors) 
git clone <repository-url>
cd mcp-server-docx
nvm install && npm install && npm run build

Use dist/index.js in your Claude config instead of the downloaded bundle.

Features

🎯 Pure Markdown Mode (Recommended)

The simplest way to create Word documents - just write natural markdown like you always do!

Just tell Claude what you want in plain markdown syntax:

Create a Word document at /tmp/my-resume.docx from this markdown:

# JANE SMITH
jane@example.com | (555) 123-4567

## PROFESSIONAL SUMMARY

I am a **senior software engineer** with *10+ years* of experience building scalable web applications.

> "Jane is an exceptional technical leader and mentor." — Former Manager

## SKILLS

- Expert in **TypeScript**, **React**, and **Node.js**
- Strong experience with **AWS** cloud architecture
- Passionate about **clean code** and **best practices**

---

## WORK EXPERIENCE

### Senior Engineer at Tech Corp (2020-Present)

Key achievements:

1. Designed and implemented **microservices architecture**
2. Reduced system latency by *40%*
3. Mentored team of 5 junior engineers

### Software Engineer at Startup Inc (2015-2020)

- Built MVP from scratch using **React** and **TypeScript**
- Implemented REST API with **Express** and **PostgreSQL**

What you get:

  • ✅ Professional Word document in ~300ms
  • ✅ Proper heading styles with borders (H1, H2)
  • ✅ Bold and italic formatting
  • ✅ Bulleted and numbered lists
  • ✅ Block quotes formatted in italics
  • ✅ Horizontal rules handled automatically
  • ✅ Proper spacing between sections
  • ✅ Times New Roman font (professional default)

Supported Markdown:

  • # ## ### Headings (H1/H2 get bottom borders)
  • **bold** and *italic* inline formatting
  • [text](url) for clickable hyperlinks
  • - or * for bullet lists
  • 1. 2. for numbered lists
  • > quote for block quotes (rendered in italics)
  • --- *** ___ horizontal rules (rendered as lines)
  • Empty lines for spacing between sections

Behind the scenes: Uses create_document_from_markdown tool

🎨 Custom Styling for Markdown

Want Helvetica instead of Times New Roman? Different font sizes? - Easily customize the appearance!

You can override the default styles by passing a styles object:

Create a Word document at /tmp/my-resume.docx from this markdown:

# JANE SMITH
## Professional Summary
I am a senior engineer.

Use these custom styles:
- All headings should be Helvetica
- H1 should be 36pt bold without bottom border
- H2 should be 24pt bold with bottom border
- Paragraphs should be Arial 12pt

Style options by element:

  • heading1, heading2, heading3, heading4 - Control heading appearance
  • paragraph - Regular paragraph text
  • bullets - Bulleted list items
  • ordered - Numbered list items
  • blockquote - Block quote text (from > quote)

Each element can have:

  • fontName - Font family (e.g., "Helvetica", "Arial", "Times New Roman")
  • fontSize - Font size in points (e.g., 12, 14, 36)
  • bold - Bold text (true/false)
  • italic - Italic text (true/false)
  • color - Text color as hex RGB (e.g., "FF0000")
  • borderBottom - Bottom border for headings (true/false)

Example styles object:

styles: {
  heading1: { fontName: 'Helvetica', fontSize: 36, bold: true, borderBottom: false },
  heading2: { fontName: 'Helvetica', fontSize: 24, bold: true, borderBottom: true },
  heading3: { fontName: 'Helvetica', fontSize: 18, bold: true },
  paragraph: { fontName: 'Arial', fontSize: 12 },
  bullets: { fontName: 'Arial', fontSize: 12 },
  ordered: { fontName: 'Arial', fontSize: 12 },
  blockquote: { fontName: 'Georgia', fontSize: 12, italic: true }
}

Default styles (used when you don't provide custom styles):

  • Headings: Times New Roman, bold, H1=24pt, H2=18pt, H3/H4=14/12pt
  • H1/H2: Bottom borders, H3/H4: No borders
  • Paragraphs/Lists: Times New Roman, 12pt
  • Blockquotes: Times New Roman, 12pt, italic

Pro tip: You only need to specify the elements/properties you want to change! Unspecified elements use the defaults.

⚡ Batch Mode with Structured Content

For when you need fine-grained control - specify exact fonts, sizes, and colors

Use this when markdown isn't flexible enough and you need precise control over formatting:

Create a resume at /tmp/my-resume.docx using create_document_from_content.

Make the name "JANE SMITH" in Helvetica 36pt bold.
Add a "PROFESSIONAL SUMMARY" H2 heading with a bottom border in Helvetica 14pt.
Add a paragraph about my experience in Times New Roman 12pt.
Add a "SKILLS" H2 heading with a bottom border.
Add bullet points for my skills in Times New Roman 12pt.

Example structure:

content: [
  {
    text: 'JANE SMITH', // defaults to paragraph type
    format: { fontName: 'Helvetica', fontSize: 36, bold: true },
  },
  { text: '' }, // empty paragraph for spacing
  {
    type: 'heading',
    text: 'PROFESSIONAL SUMMARY',
    format: { level: 2, borderBottom: true },
  },
  {
    text: 'Software engineer with 10+ years experience...',
    format: { fontName: 'Times New Roman', fontSize: 12 },
  },
  {
    type: 'bullets',
    items: ['TypeScript & React', 'Node.js & Python', 'AWS & Docker'],
    format: { fontName: 'Times New Roman', fontSize: 12 },
  },
];

Content item options:

  • type: 'paragraph' (default), 'heading', 'bullets', 'ordered'
  • text: For paragraphs and headings (use '' for spacing)
  • items: Array of strings for lists
  • format: fontName, fontSize, bold, italic, color, level (headings), borderBottom (headings)

Behind the scenes: Uses create_document_from_content tool

📝 Using Markdown Formatting in Structured Content

You can use markdown-style formatting even in structured mode!

Both the pure markdown approach and structured content support inline **bold** and *italic* formatting:

// Markdown formatting works in any text field:
{
  text: 'Led **4-engineer team** building *next-gen platform*',
  format: { fontSize: 12 }
}

// Also works in list items:
{
  type: 'bullets',
  items: [
    'Expert in **TypeScript** and **React**',
    'Passionate about *clean code* and *best practices*'
  ]
}

This gets automatically converted to proper Word formatting with bold and italic runs.

Contributing & Local Development

Installation

git clone <repository-url>
cd mcp-server-docx
nvm install  # Use the correct Node.js version from .nvmrc
npm install
npm run build

Creating a Release

This project uses automated GitHub releases. See for details.

Quick summary:

  1. Update version in package.json (e.g., npm version patch)
  2. Create PR and merge to main
  3. GitHub Actions automatically creates a release with the bundled index.js

The release workflow only triggers on changes to:

  • src/** (excluding tests)
  • package.json
  • package-lock.json

Testing

Comprehensive test suite with 54 tests powered by Vitest:

npm test              # Run tests once
npm run test:watch    # Watch mode with fast HMR
npm run test:coverage # Coverage report
npm run test:ui       # Visual UI mode

Test coverage:

  • Markdown parsing (headings, lists, block quotes, horizontal rules, inline formatting, links)
  • Auto-session creation
  • Paragraph, heading, and list formatting
  • Link support in paragraphs, headings, and lists
  • Horizontal rule rendering
  • Color formatting for all element types
  • Batch document creation
  • Error handling
  • Complex multi-section documents
  • Spacing between elements

Performance: All 54 tests complete in ~400ms

Code Quality

npm run lint         # Run ESLint (fails on warnings)
npm run lint:fix     # Auto-fix linting issues
npm run format       # Format code with Prettier
npm run format:check # Check formatting (CI)
npm run typecheck    # TypeScript type checking
npm run ci           # Run all checks (lint + format + test + typecheck)

Standards:

  • TypeScript with strict mode
  • ESLint (no warnings allowed)
  • Prettier (single quotes, 2-space indent, 100 char width)
  • GitHub Actions CI on all PRs

Project Structure

mcp-server-docx/
├── src/
│   ├── __tests__/
│   │   ├── document-manager.test.ts  # Document management tests
│   │   └── markdown-parser.test.ts   # Markdown parsing tests
│   ├── index.ts              # MCP server implementation
│   ├── document-manager.ts   # Core document logic
│   ├── markdown-parser.ts    # Markdown to content converter
│   └── types.ts              # TypeScript type definitions
├── dist/                     # Compiled JavaScript
├── vitest.config.ts          # Test configuration
├── package.json
├── tsconfig.json
└── README.md

Performance & Architecture

Key Performance Metrics:

  • Single document creation: ~300ms
  • Full resume (batch mode): ~300ms vs 3-5s (incremental) vs ~35s (Python)
  • 100x faster than Python implementation
  • 20-30x fewer MCP calls (1 batch call vs 20-30 incremental)

Design Principles:

  1. Batch Operations - Create entire documents in a single MCP call
  2. In-Memory Storage - Documents stored in memory until save (eliminates file I/O overhead)
  3. Auto-Session Creation - No explicit initialization needed, start adding content immediately
  4. Smart Markdown Parsing - Single-pass parsing with inline **bold**/*italic* support
  5. Default Styling - Times New Roman applied automatically for professional appearance
  6. Type Safety - Full TypeScript definitions for correctness

Future Enhancements

  • Tables and images
  • Custom style definitions
  • Headers, footers, and page breaks
  • Search & replace functionality

License

ISC

Author

James Mehorter

Acknowledgments

This project is built on two excellent open source libraries:

Document Generation: docx

docx.js.org | GitHub - A powerful library for generating Word documents (.docx files) in JavaScript/TypeScript. This MCP server wouldn't be possible without the solid foundation that docx provides for creating and manipulating Office Open XML documents.

Markdown Parsing: remark

remark.js.org | GitHub - A robust markdown processor powered by plugins, part of the unified collective. Remark's standards-compliant parsing ensures accurate conversion of markdown to Word documents.

Thanks to:

  • Dolan Miu and all contributors to the docx library
  • Titus Wormer and the unified collective for remark
  • The Anthropic team for building the Model Context Protocol and Claude Code
  • The open source community for making tools like this possible