# 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
1. Install dependencies:
```bash
npm install
```
2. Create a `.env` file (Optional, defaults to `./output`):
```
OUTPUT_DIR=./generated_reports
```
3. Build and start:
```bash
npm run build
npm start
```
### 2. Docker Usage
**Critical Note:** Because this server creates files, you must mount a volume to see the output.
1. Build the image:
```bash
docker build -t word-mcp .
```
2. Run with Volume Mapping:
```bash
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.
1. Open your config file:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
2. Add this configuration:
```json
{
"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:
```yaml
# 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.
```json
{
"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:
```bash
npm run dev
```
Watch for changes:
```bash
npm run watch
```
