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 Releases 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!

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 RELEASING.md 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