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!

<details> <summary><b>Build from Source</b> (for contributors)</summary>

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.

</details>

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