Word MCP

A Model Context Protocol (MCP) server for generating Microsoft Word documents (.docx) programmatically. Unlike typical MCP servers that act as gateways to APIs, this server acts as a Factory, converting AI-generated text and data into professional, downloadable files.

Features

Document Generation

generate_report: Create complete Word documents in one shot
Markdown Support: Automatically converts basic Markdown (bold, lists) into Word formatting
Rich Elements: Supports:
- Headers (Levels 1-3)
- Data Tables with custom headers
- Text Paragraphs
- File metadata (Titles, Authors)

Architecture

Local File Output: Saves files directly to your host machine
Dockerized Factory: Runs securely in a container with volume mapping
Stateless Operation: No complex databases required

Simple Setup

1. Local Development

Install dependencies:
```
npm install
```
Create a .env file (Optional, defaults to ./output):
```
OUTPUT_DIR=./generated_reports
```
Build and start:
```
npm run build
npm start
```

2. Docker Usage

Critical Note: Because this server creates files, you must mount a volume to see the output.

Build the image:
```
docker build -t word-mcp .
```

Run with Volume Mapping:

docker run --rm -i \
  -v $(pwd)/generated_reports:/app/output \
  word-mcp

MCP Client Integration

Configuration for Claude Desktop

To allow the AI to save files to your Windows "Documents" folder, you must map the volume in the configuration.

Open your config file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "word-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "C:\\Users\\hp\\Documents\\mcp\\word-mcp\\generated_reports:/app/output",
        "word-mcp"
      ]
    }
  }
}

Note: Update the path C:\\Users\\hp... to match your actual project location.

Using with Docker Compose

If you prefer docker-compose, use the included configuration:

# docker-compose.yml
services:
  word-mcp:
    build: .
    volumes:
      - ./generated_reports:/app/output

Usage Examples

Generate a Project Audit

The AI can call the tool with structured data to create a formatted report.

{
  "filename": "Audit_Report_2024",
  "title": "Q4 Security Audit",
  "sections": [
    {
      "heading": "Executive Summary",
      "content": "The audit was completed on **January 20th**. No critical vulnerabilities were found."
    },
    {
      "heading": "Vulnerability Matrix",
      "table": {
        "headers": ["Severity", "Count", "Status"],
        "rows": [
          ["High", "0", "Pass"],
          ["Medium", "2", "Investigating"]
        ]
      }
    }
  ]
}

Troubleshooting

"I can't find the generated file"

Check Volume Mapping: Ensure your claude_desktop_config.json has the -v flag pointing to a valid folder on your host machine.
Docker Permissions: The container runs as a non-root user (appuser). Ensure your host folder allows writing (usually automatic on Windows, but requires chmod on Linux).

"Error: Output directory does not exist"

The server attempts to create the directory on startup. If using Docker, ensure the internal path /app/output is correctly mapped.

"Formatting looks wrong"

Currently, the Markdown parser supports bold (**text**) and basic paragraph splitting. Complex Markdown (like code blocks or nested lists) will be rendered as plain text in this version.

Development

Run in development mode:

npm run dev

Watch for changes:

npm run watch

word-mcp