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```bash
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```bash
# Install dependencies
pip install -r requirements.txt
# Or using pyproject.toml
pip install -e .
Using uv (recommended)```bash
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:```bash
# Using python directly
python main.py
# Using uv
uv run python main.py
HTTP Mode
For network access and multiple clients:```bash
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```bash
# 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.```python
{
"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 filenamedocuments://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):```json
{
"mcpServers": {
"documents-work": {
"command": "uv",
"args": ["run", "python", "C:/Users/batashev/Desktop/MyProjects/docx_mcp/main.py"],
"env": {}
}
}
}
### Alternative configurations:
#### Using relative path:```json
{
"mcpServers": {
"documents-work": {
"command": "uv",
"args": ["run", "python", "main.py"],
"cwd": "C:/Users/batashev/Desktop/MyProjects/docx_mcp"
}
}
}
Using pip instead of uv:```json
{
"mcpServers": {
"documents-work": {
"command": "python",
"args": ["C:/Users/batashev/Desktop/MyProjects/docx_mcp/main.py"]
}
}
}
#### With custom output directory:```json
{
"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```python
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```python
# 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```bash
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.