MCP Documents

🚀 Document Generator MCP Server

The MCP (Model Context Protocol) server is designed to generate DOCX and PDF documents, supporting both STDIO and HTTP transports. It offers an efficient and flexible solution for document creation.

🚀 Quick Start

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: Fully support paragraphs, tables, and styling.
• Create PDF documents: Generate PDFs containing text and tables.
• Session management: Build documents incrementally.
• Multiple transports: Use STDIO for local CLI and HTTP for network access.
• Clean architecture: Separate domain, infrastructure, and presentation layers.
• Base64 support: Return small documents as base64.
• 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 an editable package
uv pip install -e .

# Create a virtual environment with uv
uv venv

💻 Usage Examples

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 a structure similar 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.

🔧 Technical Details

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

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

HTTP Transport

• Run a web server on a specified port.
• Support multiple concurrent clients.
• Provide 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"
      }
    }
  }
}

💻 Usage 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.