Doc Ops Mcp

Document Operations MCP Server

[](https://www.npmjs.com/package/doc-ops-mcp) [](https://opensource.org/licenses/MIT) [](https://www.npmjs.com/package/doc-ops-mcp)

Language / 语言: [English](README.md) | [中文](README_zh.md)

> Document Operations MCP Server - A universal MCP server for document processing, conversion, and automation. Handle PDF, DOCX, HTML, Markdown, and more through a unified API and toolset.

Demo

Video

In this demo, we showcase how to:

• Configure doc-ops-mcp in MCP clients
• Convert DOCX documents to PDF format
• Add default watermarks to converted PDF files

Table of Contents

1. [Quick Start](#1-quick-start)
2. [System Architecture](#2-system-architecture)
3. [Optional Integration](#3-optional-integration)
4. [Features](#4-features)
5. [Open Source Licenses](#5-open-source-licenses)
6. [Future Roadmap](#6-future-roadmap)
7. [Docker Deployment](#7-docker-deployment)
8. [Development Guide](#8-development-guide)
9. [Troubleshooting](#9-troubleshooting)
10. [Contributing](#10-contributing)

1. Quick Start

First, add the Document Operations MCP server to your MCP client.

Standard config works in most MCP clients:

{
  "mcpServers": {
    "doc-ops-mcp": {
      "command": "npx",
      "args": ["-y", "doc-ops-mcp"],
      "env": {
        "OUTPUT_DIR": "/path/to/your/output/directory",
        "CACHE_DIR": "/path/to/your/cache/directory",
      }
    }
  }
}

Claude Desktop

Follow the MCP install guide, use the standard config above.

VS Code

Follow the MCP install guide, use the standard config above.

Cursor

Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx -y doc-ops-mcp.

Other MCP Clients

For other MCP clients, use the standard config above and refer to your client's documentation for MCP server installation.

Configuration

The Document Operations MCP server supports configuration through environment variables. These can be provided in the MCP client configuration as part of the "env" object:

{
  "mcpServers": {
    "doc-ops-mcp": {
      "command": "npx",
      "args": ["-y", "doc-ops-mcp"],
      "env": {
        "OUTPUT_DIR": "/path/to/your/output/directory",
        "CACHE_DIR": "/path/to/your/cache/directory",
        "WATERMARK_IMAGE": "/path/to/watermark.png",
        "QR_CODE_IMAGE": "/path/to/qrcode.png"
      }
    }
  }
}

Supported Document Operations

| Format | Convert to PDF | Convert to DOCX | Convert to HTML | Convert to Markdown | Content Rewriting | Watermark/QR Code | |--------|----------------|-----------------|-----------------|---------------------|-------------------|-------------------| | PDF | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | | DOCX | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | | HTML | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | | Markdown | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |

Rewriting Features:

• Content Replacement: Support batch text replacement and regular expression replacement
• Format Adjustment: Modify document structure, heading levels, and style formatting
• Smart Rewriting: Content optimization while preserving original document format

Usage Examples

Format Conversion:

Convert /Users/docs/report.docx to PDF
Convert /Users/docs/article.md to HTML
Convert /Users/docs/presentation.html to DOCX
Convert /Users/docs/readme.md to PDF (with theme styling)

Document Rewriting:

Rewrite company names in /Users/docs/contract.md
Batch replace terminology in /Users/docs/manual.docx
Adjust heading levels in /Users/docs/article.html
Update dates and version numbers in /Users/docs/policy.md

PDF Enhancement:

Add watermark to /Users/docs/document.pdf
Add QR code to /Users/docs/report.pdf
Add company logo watermark to /Users/docs/invoice.pdf

Environment Variables

The server supports environment variables for controlling output paths and PDF enhancement features:

Core Directories

• OUTPUT_DIR: Controls where all generated files are saved (default: ~/Documents)
• CACHE_DIR: Directory for temporary and cache files (default: ~/.cache/doc-ops-mcp)

PDF Enhancement Features

• WATERMARK_IMAGE: Default watermark image path for PDF files
• Automatically added to all PDF conversions
• Supported formats: PNG, JPG
• If not set, default text watermark "doc-ops-mcp" will be used
• QR_CODE_IMAGE: Default QR code image path for PDF files
• Added to PDFs only when explicitly requested (addQrCode=true)
• Supported formats: PNG, JPG
• If not set, QR code functionality will be unavailable

Output Path Rules:

1. If outputPath is not provided → files saved to OUTPUT_DIR with auto-generated names
2. If outputPath is relative → resolved relative to OUTPUT_DIR
3. If outputPath is absolute → used as-is, ignoring OUTPUT_DIR

See [OUTPUTPATHCONTROL.md](./OUTPUTPATHCONTROL.md) for detailed documentation.

2. System Architecture

Document Operations MCP Server adopts a pure JavaScript architecture design, providing complete document processing capabilities:

┌─────────────────────────────────────────────────────────────┐
│                    MCP Client Layer                         │
│           (Claude Desktop, Cursor, VS Code, etc.)           │
└─────────────────────┬───────────────────────────────────────┘
                      │ JSON-RPC 2.0
┌─────────────────────┴───────────────────────────────────────┐
│                 Doc-Ops-MCP Server                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │   Tool Router   │  │  Request        │  │  Response   │ │
│  │   & Handler     │  │  Validator      │  │  Formatter  │ │
│  └────────┬────────┘  └────────┬────────┘  └──────┬──────┘ │
│           │                    │                  │        │
│  ┌────────┴────────────────────┴──────────────────┴─────┐ │
│  │                Document Processing Engine             │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │  Document   │  │   Format    │  │   Style     │   │ │
│  │  │   Reader    │  │  Converter  │  │  Processor  │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │ │
│  │                                                        │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │ │
│  │  │    PDF      │  │  Watermark/ │  │ Conversion  │   │ │
│  │  │ Enhancement │  │   QR Code   │  │  Planner    │   │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │ │
└────┴───────────────────────────────────────────────────────┴─┘
                            │
┌───────────────────────────┴─────────────────────────────────┐
│                    Core Dependencies Layer                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   pdf-lib   │  │word-extractor│  │   marked    │          │
│  │ (PDF Tools) │  │(DOCX Reader)│  │ (Markdown)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   cheerio   │  │    jszip    │  │    docx     │          │
│  │(HTML Parser)│  │(ZIP Handler)│  │(DOCX Gen.)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────┐  ┌─────────────┐                           │
│  │   xml2js    │  │Custom OOXML │                           │
│  │(XML Parser) │  │   Parser    │                           │
│  └─────────────┘  └─────────────┘                           │
└─────────────────────────────────────────────────────────────┘

Architecture Overview

Core Features:

• Pure JavaScript implementation with no external system dependencies
• Complete document reading, conversion, and style processing capabilities
• Built-in PDF watermark and QR code addition functionality
• Intelligent conversion planning and path optimization

Conversion Flow:

• Direct Conversion: Supports direct conversion between most formats
• Multi-step Conversion: Complex conversions achieved through intermediate formats
• Style Preservation: Uses OOXML parser to ensure complete style integrity

3. Optional Integration

This server can work with playwright-mcp for enhanced PDF conversion capabilities. Please refer to the official playwright-mcp documentation for detailed configuration.

🔧 PDF Conversion Workflow

This server supports complete PDF conversion functionality:

1. Document Parsing: Use OOXML parser to ensure complete style preservation
2. Format Conversion: Convert documents to high-quality HTML format
3. PDF Generation: Built-in converter or optionally work with playwright-mcp
4. Enhancement Processing: Automatically add watermarks and QR codes (if configured)

How It Works

This server uses intelligent conversion architecture:

1. Smart Planning: plan_conversion analyzes conversion requirements and selects optimal paths
2. Format Conversion: Use specialized converters to handle various document formats
3. Style Preservation: Ensure style integrity through OOXML parser
4. Enhancement Processing: Automatically add watermarks, QR codes and other enhancements
5. Optional Integration: Support working with playwright-mcp for enhanced capabilities

4. Features

MCP Tools

Core Document Tools

| Tool Name | Description | Input Parameters | External Dependencies | |-----------|-------------|------------------|----------------------| | read_document | Read document content | filePath: Document pathextractMetadata: Extract metadatapreserveFormatting: Preserve formatting | None | | write_document | Write document content | content: Document contentoutputPath: Output file pathencoding: File encoding | None | | convert_document | Smart document conversion | inputPath: Input file pathoutputPath: Output file pathpreserveFormatting: Preserve formatting | None | | plan_conversion | Conversion planner | sourceFormat: Source formattargetFormat: Target formatpreserveStyles: Preserve stylesquality: Conversion quality | None |

read_document

Read various document formats including PDF, DOCX, DOC, HTML, MD, and more.

Parameters:

• filePath (string, required) - Document path to read
• extractMetadata (boolean, optional) - Extract document metadata, defaults to false
• preserveFormatting (boolean, optional) - Preserve formatting (HTML output), defaults to false

write_document

Write content to document files in specified formats.

Parameters:

• content (string, required) - Content to write
• outputPath (string, optional) - Output file path (auto-generated if not provided)
• encoding (string, optional) - File encoding, defaults to utf-8

convert_document

Convert documents between formats with enhanced style preservation.

Parameters:

• inputPath (string, required) - Input file path
• outputPath (string, optional) - Output file path (auto-generated if not provided)
• preserveFormatting (boolean, optional) - Preserve formatting, defaults to true
• useInternalPlaywright (boolean, optional) - Use built-in Playwright for PDF conversion, defaults to false

convertdocxto_pdf

Convert DOCX to PDF with automatic watermark addition (if configured).

Parameters:

• docxPath (string, required) - DOCX file path
• outputPath (string, optional) - Output PDF path (auto-generated if not provided)
• addQrCode (boolean, optional) - Whether to add QR code, defaults to false
• preserveFormatting (boolean, optional) - Preserve original formatting, defaults to true
• chineseFont (string, optional) - Chinese font, defaults to Microsoft YaHei

convertmarkdownto_pdf

Convert Markdown to PDF with automatic watermark addition (if configured).

Parameters:

• markdownPath (string, required) - Markdown file path
• outputPath (string, optional) - Output PDF path (auto-generated if not provided)
• theme (string, optional) - Theme style, defaults to "github"
• includeTableOfContents (boolean, optional) - Include table of contents, defaults to false
• addQrCode (boolean, optional) - Whether to add QR code, defaults to false

convertmarkdownto_html

Convert Markdown to HTML.

Parameters:

• markdownPath (string, required) - Markdown file path
• outputPath (string, optional) - Output HTML path (auto-generated if not provided)
• theme (string, optional) - Theme style, defaults to "github"
• includeTableOfContents (boolean, optional) - Include table of contents, defaults to false

convertmarkdownto_docx

Convert Markdown to DOCX.

Parameters:

• markdownPath (string, required) - Markdown file path
• outputPath (string, optional) - Output DOCX path (auto-generated if not provided)

converthtmlto_markdown

Convert HTML to Markdown.

Parameters:

• htmlPath (string, required) - HTML file path
• outputPath (string, optional) - Output Markdown path (auto-generated if not provided)

plan_conversion

🎯 Smart Conversion Planner - Analyze conversion requirements and generate optimal conversion plans.

Parameters:

• sourceFormat (string, required) - Source file format (pdf, docx, html, markdown, md, txt, doc)
• targetFormat (string, required) - Target file format (pdf, docx, html, markdown, md, txt, doc)
• sourceFile (string, optional) - Source file path (for generating specific conversion parameters)
• preserveStyles (boolean, optional) - Whether to preserve style formatting, defaults to true
• includeImages (boolean, optional) - Whether to include images, defaults to true
• theme (string, optional) - Conversion theme, defaults to github
• quality (string, optional) - Conversion quality requirement (fast, balanced, high), defaults to balanced

processpdfpost_conversion

Parameters:

• playwrightPdfPath (string, required) - Generated PDF file path
• targetPath (string, optional) - Target PDF file path (auto-generated if not provided)
• addWatermark (boolean, optional) - Whether to add watermark, defaults to false
• addQrCode (boolean, optional) - Whether to add QR code, defaults to false
• watermarkImage (string, optional) - Watermark image path
• qrCodePath (string, optional) - QR code image path

PDF Enhancement Tools

add_watermark

🎨 PDF Watermark Addition Tool - Add image or text watermarks to PDF documents.

Parameters:

• pdfPath (string, required) - PDF file path
• watermarkImage (string, optional) - Watermark image path (PNG/JPG)
• watermarkText (string, optional) - Watermark text content
• watermarkImageScale (number, optional) - Image scale ratio, defaults to 0.25
• watermarkImageOpacity (number, optional) - Image opacity, defaults to 0.6
• watermarkImagePosition (string, optional) - Image position, defaults to fullscreen

add_qrcode

📱 PDF QR Code Addition Tool - Add QR codes to PDF documents.

Parameters:

• pdfPath (string, required) - PDF file path
• qrCodePath (string, optional) - QR code image path
• qrScale (number, optional) - QR code scale ratio, defaults to 0.15
• qrOpacity (number, optional) - QR code opacity, defaults to 1.0
• qrPosition (string, optional) - QR code position, defaults to bottom-center
• addText (boolean, optional) - Whether to add explanatory text, defaults to true

System Requirements

System Requirements

• Node.js ≥ 18.0.0
• Zero external system dependencies - All processing via npm packages
• Optional Integration: playwright-mcp for enhanced PDF conversion

Core Technology Stack

• pdf-lib - PDF operations and enhancement
• word-extractor - DOCX document text extraction
• marked - Markdown parsing and rendering
• **cheer

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Tele-AI
• Source: Tele-AI/doc-ops-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.