opendoc-mcp
High-performance Rust MCP server for document CRUD operations — purpose-built for AI agents.
opendoc-mcp is a pure-Rust implementation of the Model Context Protocol (MCP) server that gives AI assistants (Claude, ChatGPT, Cursor, VS Code, etc.) direct, native access to create, read, edit, convert, and manage Office documents and PDFs — without external dependencies, LibreOffice, cloud APIs, or heavy runtimes.
One binary. Zero deps. All formats. Lightning fast.
Features
Supported Formats
Unified Tools & Capabilities
Document Intelligence
open_document— Open any document and return structured JSON (takesdetail_level:full,summary,metadata_only)read_document_text— Extract plain text from any documentsearch_document— Find keywords or regex matchesreplace_text— Regex-powered text replacement (operates on IR)diff_documents— LCS paragraph-level document comparisonchunk_for_embedding— Text chunking for RAG / embeddingsfill_template— Template variable substitution (takes raw JSONvariablesobject)validate_document— Inspect document structural soundness
Format Conversion
convert— Cross-format conversion (DOCX↔PDF, DOCX→MD, XLS→CSV, etc.)create_html— Convert document to styled HTML
Batch Processing
batch_convert— Parallel conversion of a whole directory of documents
Authoring & Editing
- DOCX:
create_docx,docx_add_paragraph,docx_add_table,docx_add_image - PPTX:
create_pptx,pptx_add_slide - XLSX:
create_xlsx(takes raw JSONsheetsarray) - PDF:
create_pdf,merge_pdfs,extract_pdf_text,list_pdf_fields,fill_pdf_form(takes raw JSONvaluesobject)
Metadata & Analysis
find_tables— Extract table coordinates and metadataanalyze_document_complexity— Complexity analysis (OCR needs, page scans)
AI Features
ocr_document— Feature-gated OCR for scanned docs (requires--features ocr)check_ocr_available— Check OCR engine status
Utility
list_capabilities— Category list of all consolidated tools
MCP Resources
opendoc-mcp exposes documents directly as read-only MCP resources:
doc://{absolute_path}— Exposes the plain text content of a documentdoc://{absolute_path}/outline— Exposes the JSON outline of a document (sections, heading hierarchy)
These can be read directly by agents without tool calls using standard resource read requests.
Structured Errors ("Errors as Instructions")
All tool errors return structured JSON payloads to help AI agents recover dynamically:
{
"error": "Detailed description of the error...",
"error_code": "FILE_IO_ERROR",
"category": "io",
"suggestion": "Verify the file exists at the specified path..."
}
Quick Start
Installation
cargo install opendoc-mcp
Or build from source:
git clone https://github.com/yourusername/opendoc-mcp.git
cd opendoc-mcp
cargo build --release
./target/release/opendoc-mcp
Configuration
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"opendoc-mcp": {
"command": "/path/to/opendoc-mcp"
}
}
}
VS Code (Cline / Roo Code)
Add to your MCP settings:
{
"servers": {
"opendoc-mcp": {
"command": "/path/to/opendoc-mcp"
}
}
}
Cursor
Configure in Cursor Settings → MCP Servers → Add:
Name: opendoc-mcp
Type: stdio
Command: /path/to/opendoc-mcp
Performance
opendoc-mcp is designed for AI agent workloads where every millisecond counts:
Architecture
┌─────────────────────────────────────────┐
│ MCP Client (Host) │
│ Claude / Cursor / VS Code / Custom │
└──────────────┬──────────────────────────┘
│ JSON-RPC over stdio
▼
┌─────────────────────────────────────────┐
│ opendoc-mcp Server │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │ DOCX │ │ PPTX │ │ PDF │ │
│ │ Handler │ │ Handler │ │Handler │ │
│ └────┬─────┘ └────┬─────┘ └───┬────┘ │
│ │ │ │ │
│ ┌────┴──────────────┴────────────┴────┐ │
│ │ Rust Core (rmcp) │ │
│ │ MCP Protocol · Transport · Tools │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
Key design decisions:
- Single binary — No runtime dependencies, no npm/pip, no LibreOffice
- Stdio transport — Zero networking overhead, instant startup
- Pure Rust — Memory-safe, thread-safe, predictable performance
- Modular handlers — Each format is isolated; adding new formats is trivial
Development
# Check compilation
cargo check
# Run tests
cargo test
# Build release
cargo build --release
# Run with logging
RUST_LOG=debug cargo run
Project Structure
opendoc-mcp/
├── Cargo.toml
├── README.md
├── assets/ # Logos, branding
├── benches/ # Criterion benchmarks
├── docs/
│ ├── architecture.md
│ ├── changelog.md
│ ├── implementationplan.md
│ ├── spec.md
│ └── superpowers/ # Advanced usage guides
├── src/
│ ├── main.rs # Entry point: MCP server or CLI
│ ├── lib.rs # Module exports
│ ├── server.rs # MCP #[tool] definitions
│ ├── cli.rs # CLI subcommands (clap)
│ ├── ir/ # Internal Representation (Document, Paragraph, etc.)
│ ├── engine/ # search, replace, template, diff, complexity
│ ├── handlers/ # docx/pptx/pdf/xlsx/html/md/csv/pdf_forms
│ ├── converters/ # Cross-format conversion
│ ├── batch/ # Rayon-parallel batch processing
│ ├── validators/ # Document structure validation
│ ├── ocr/ # Feature-gated OCR (--features ocr)
│ └── security.rs # Path validation sandbox
└── tests/
└── common/ # Shared test utilities
Roadmap
v0.0.2 ✅ — IR engine, format expansion (XLSX, HTML, MD, CSV), batch processing, CLI, benchmarks, doc comments v0.0.3 ✅ — Enhanced template engine, multi-page PDF with layout, DOCX image insertion, 80%+ test coverage v0.0.4 ✅ — Text chunking for RAG, image extraction, PDF split by range, password support v0.0.5 ✅ — Batch operations conversion CLI/MCP tool extensions, direct conversion performance profiling v0.0.6 ✅ — Spreadsheet Write, Update, & Edit Support (XLSX) v0.0.7 ✅ — Visual Document Diffing (HTML/Markdown highlights) v0.0.8 ✅ — Enhanced DOCX/PPTX styling and layout options v0.0.9 ✅ — Scanned PDF & Image OCR Integration v0.0.11 ✅ — Document Vision (Screenshots), Recursive ZIP archive digests, and Domain template extractions v0.0.12 ✅ — WASM target support and PDF/A compliance validator v0.1.0 🔄 — Digital signatures, streamable HTTP transport, security hardening v1.0.0 — Production-ready: enterprise security, full format coverage
See docs/implementationplan.md for details.
Local Installation & Updates
To compile and install the binary globally in your user space (installs to ~/.local/bin/):
./localinstall.sh
When you make changes to the source code or pull new updates, rebuild and update your global installation:
./localupdate.sh
System Requirements & Performance
opendoc-mcp is designed to be extremely lightweight and highly performant:
- RAM: ~3-5 MB (Idle), scaling up to only ~20-30 MB under heavy batch processing or OCR.
- ROM (Storage): ~5 MB (single self-contained compiled binary).
- Processor: Fully supported on single-core or multi-core x86_64 and ARM processors. Batch conversion and complex parsing scale automatically across multiple cores using
rayon. - Speed: Sub-10ms startup time. Operations like text extraction, replacement, template parsing, and conversion typically execute in under 2-15ms.
Comparison with Other MCP Servers
Why Rust for AI Agent Tools?
AI agents need tool servers that are:
- Fast — Sub-millisecond startup, no warm-up
- Lightweight — Minimal RAM/CPU so many can run in parallel
- Reliable — No garbage collection pauses, no runtime crashes
- Portable — Single binary for any platform (Linux, macOS, Windows)
Rust delivers all of this. Most document MCP servers today are Node.js or Python — opendoc-mcp is the first pure-Rust alternative.
License
MIT License — see LICENSE for details.
Contributing
Contributions welcome! Areas needing help:
- Multi-page PDF layout and rendering
- Template engine for document generation (nested objects, loops)
- DOCX image insertion
- WASM compilation target
- Additional format support (ODT, JSON)