Document Generator MCP Server

MCP (Model Context Protocol) server for creating DOCX and PDF documents with support for both STDIO and HTTP transports.

⚡ Quick Start with uv

# Clone the repository
git clone <repository-url>
cd docx_mcp

# Install uv if you haven't already
pip install uv

# Setup environment and install dependencies
uv venv
uv pip install -e .

# Run the server
uv run python main.py

🚀 Features

Create DOCX documents - Full support for paragraphs, tables, and styling
Create PDF documents - Generate PDFs with text and tables
Session management - Build documents incrementally
Multiple transports - STDIO for local CLI, HTTP for network access
Clean architecture - Separated domain, infrastructure, and presentation layers
Base64 support - Return documents as base64 for small files
MCP Resources - Access generated documents via URIs

📦 Installation

Using pip

# Install dependencies
pip install -r requirements.txt

# Or using pyproject.toml
pip install -e .

Using uv (recommended)

# Install dependencies with uv
uv pip install -r requirements.txt

# Or install as editable package
uv pip install -e .

# Create virtual environment with uv
uv venv

🎯 Usage

STDIO Mode (Default)

For local CLI tools and desktop applications:

# Using python directly
python main.py

# Using uv
uv run python main.py

HTTP Mode

For network access and multiple clients:

# Using python directly
python main.py --transport http --host 0.0.0.0 --port 8000

# Using uv
uv run python main.py --transport http --host 0.0.0.0 --port 8000

Using FastMCP CLI

# STDIO mode
fastmcp run presentation/server.py:mcp
# Or with uv
uv run fastmcp run presentation/server.py:mcp

# HTTP mode
fastmcp run presentation/server.py:mcp --transport http --port 8000
# Or with uv
uv run fastmcp run presentation/server.py:mcp --transport http --port 8000

🛠 Available Tools

`create_docx`

Create a complete DOCX document in one call.

{
    "title": "My Document",
    "paragraphs": [
        "Simple text paragraph",
        {
            "text": "Styled paragraph",
            "style": "bold",
            "alignment": "center",
            "font_size": 14
        }
    ],
    "tables": [
        {
            "headers": ["Name", "Age"],
            "data": [["Alice", "30"], ["Bob", "25"]]
        }
    ],
    "return_base64": false
}

`create_pdf`

Create a PDF document with similar structure to DOCX.

`create_document_session`

Start a session for building a document incrementally.

`add_paragraph`

Add a paragraph to a document in session.

`add_table`

Add a table to a document in session.

`save_document`

Save a session document as DOCX or PDF.

`list_documents`

List all documents in the current session.

🏗 Architecture

docx_mcp/
├── core/               # Domain layer (business logic)
│   ├── models/        # Document, Paragraph, Table models
│   └── interfaces/    # Writer interfaces
├── infrastructure/     # Infrastructure layer
│   ├── docx_writer.py # python-docx implementation
│   └── pdf_writer.py  # fpdf2 implementation
├── application/        # Application layer
│   └── services/      # Document service
├── presentation/       # Presentation layer
│   └── server.py      # FastMCP server with tools
└── main.py            # Entry point

📋 MCP Resources

Documents can be accessed via MCP Resources:

documents://{filename} - Get document content by filename
documents://list - List all generated documents

🔄 Transport Modes

STDIO Transport

Communication via standard input/output
Each client spawns a new server process
Ideal for CLI tools and desktop apps

HTTP Transport

Web server on specified port
Supports multiple concurrent clients
Full bidirectional communication
URL: http://host:port/mcp

⚙️ MCP Client Configuration

Claude Desktop Configuration

Windows

Add to your Claude Desktop config file (%APPDATA%\Claude\claude_desktop_config.json):

macOS/Linux

Add to your Claude Desktop config file (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "documents-work": {
      "command": "uv",
      "args": ["run", "python", "C:/Users/batashev/Desktop/MyProjects/docx_mcp/main.py"],
      "env": {}
    }
  }
}

Alternative configurations:

Using relative path:

{
  "mcpServers": {
    "documents-work": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "C:/Users/batashev/Desktop/MyProjects/docx_mcp"
    }
  }
}

Using pip instead of uv:

{
  "mcpServers": {
    "documents-work": {
      "command": "python",
      "args": ["C:/Users/batashev/Desktop/MyProjects/docx_mcp/main.py"]
    }
  }
}

With custom output directory:

{
  "mcpServers": {
    "documents-work": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "C:/Users/batashev/Desktop/MyProjects/docx_mcp",
      "env": {
        "OUTPUT_DIR": "C:/Users/batashev/Documents/generated_docs"
      }
    }
  }
}

📝 Examples

Create a simple DOCX

# Using MCP client
result = await client.call_tool("create_docx", {
    "title": "Hello World",
    "paragraphs": ["This is a test document"],
    "return_base64": true
})

Build document incrementally

# Create session
session = await client.call_tool("create_document_session", {
    "title": "Report"
})

# Add content
await client.call_tool("add_paragraph", {
    "document_id": session["document_id"],
    "text": "Introduction",
    "style": "bold"
})

# Save as PDF
result = await client.call_tool("save_document", {
    "document_id": session["document_id"],
    "format": "pdf"
})

🧪 Testing

# Test STDIO mode
python main.py
# Or with uv
uv run python main.py

# Test HTTP mode
python main.py --transport http --port 8000
# Or with uv
uv run python main.py --transport http --port 8000

# Run examples
python examples.py
# Or with uv
uv run python examples.py

# In another terminal, use curl or MCP client to test
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please follow clean architecture principles and add tests for new features.

Document Generator