# Doc Ops Mcp

> MCP server for seamless document format conversion and processing

- **Type:** MCP server
- **Install:** `agentstack add mcp-tele-ai-doc-ops-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Tele-AI](https://agentstack.voostack.com/s/tele-ai)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Tele-AI](https://github.com/Tele-AI)
- **Source:** https://github.com/Tele-AI/doc-ops-mcp

## Install

```sh
agentstack add mcp-tele-ai-doc-ops-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```json
{
  "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](https://modelcontextprotocol.io/quickstart/user), use the standard config above.

VS Code

Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), 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:

```json
{
  "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 [OUTPUT_PATH_CONTROL.md](./OUTPUT_PATH_CONTROL.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 path`extractMetadata`: Extract metadata`preserveFormatting`: Preserve formatting | None |
| `write_document` | Write document content | `content`: Document content`outputPath`: Output file path`encoding`: File encoding | None |
| `convert_document` | Smart document conversion | `inputPath`: Input file path`outputPath`: Output file path`preserveFormatting`: Preserve formatting | None |
| `plan_conversion` | Conversion planner | `sourceFormat`: Source format`targetFormat`: Target format`preserveStyles`: Preserve styles`quality`: 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`

##### **convert_docx_to_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`

##### **convert_markdown_to_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`

##### **convert_markdown_to_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`

##### **convert_markdown_to_docx**
Convert Markdown to DOCX.

**Parameters:**
- `markdownPath` (string, required) - Markdown file path
- `outputPath` (string, optional) - Output DOCX path (auto-generated if not provided)

##### **convert_html_to_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`

##### **process_pdf_post_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](https://github.com/Tele-AI)
- **Source:** [Tele-AI/doc-ops-mcp](https://github.com/Tele-AI/doc-ops-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tele-ai-doc-ops-mcp
- Seller: https://agentstack.voostack.com/s/tele-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.