mcp-genoffice
A byte-preserving Office document editing server that lets AI agents read, create, and surgically edit .docx, .pptx, .xlsx, and .pdf files without breaking layouts or untouched content. It also drives the GenOffice desktop app via CDP.
Document extraction:
genoffice_extract_text– read text from .docx, .xlsx, .pptx, and .pdf files, preserving slide/table structure.Word (.docx) tools:
genoffice_docx_blocks– list top-level blocks (paragraphs, headings, tables) with index, type, style, and text.genoffice_docx_patch– surgically rewrite paragraphs/headings by index, preserving untouched bytes and existing formatting; creates a new file.genoffice_docx_watermark– add or remove a text watermark, preserving body content; creates a new file.genoffice_docx_create– create a new .docx from scratch, with optional initial paragraphs and formatting.genoffice_docx_delete– remove specific blocks by index while preserving all other content; creates a new file.
PowerPoint (.pptx) tools:
genoffice_pptx_slides– list slides and their text elements (id, name, type, text).genoffice_pptx_patch– replace element text, preserving untouched elements and formatting (font, size, color, bullets); creates a new file.genoffice_pptx_create– create a new .pptx with one blank slide.genoffice_pptx_delete– delete elements from a slide while preserving other slides and parts; creates a new file.
GenOffice desktop app control (CDP):
genoffice_app_status– check installation and CDP debug port status.genoffice_app_launch– launch the app with CDP port open.genoffice_app_open_file– open a file in the app (macOS).genoffice_app_screenshot– capture a PNG screenshot of the app window.genoffice_app_eval– evaluate JavaScript in the app’s page context (read-only by default, mutation possible).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-genoffice extract the text from this report.docx and summarize it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-genoffice
MCP server that gives AI agents byte-preserving, surgical editing of Office documents through the GenOffice engine packages (Apache-2.0, pure TypeScript, no Electron required).
The core guarantee, inherited from GenOffice's architecture: the original file is the source of truth. Only the blocks you edit are regenerated as OOXML fragments; every untouched paragraph, style, header, comment and zip part keeps its original bytes. Layout never breaks.
Tools
Tool | Description |
| Extract readable text from |
| Parse a |
| Rewrite one or more paragraphs with a byte-preserving roundtrip; optional formatting per edit (bold/italic/color/sizePt/font); writes a new file, never touches the original |
| Set/remove a text watermark (header regenerated, body byte-preserved) |
| Create a NEW .docx from scratch (optional initial paragraphs, each with optional formatting) |
| Delete blocks (paragraphs/headings) — remaining blocks byte-preserved |
| List slides and their text elements (id, name, type, text) |
| Replace text of elements on a slide (element-level byte-preserving); optional formatting per edit (bold/italic/color/sizePt/font) |
| Create a NEW .pptx from scratch (one blank slide) |
| Delete elements from a slide (other slides/parts byte-preserved) |
| GenOffice desktop app: installed? CDP port up? (read-only) |
| Launch the app with the CDP debug port (handles auto-update relaunch) |
| Open a file in the app (macOS |
| PNG screenshot of the app window over CDP |
| Evaluate read-only JS in the app page context (DOM) |
More tools (xlsx ops) are on the roadmap.
Related MCP server: Office MCP Server
Install / run
# from source
npm install
npm start
# as a library in your MCP client (Hermes, Claude Desktop, ...)
npx -y mcp-genofficeConfigure in Hermes (~/.hermes/config.yaml):
mcp_servers:
genoffice:
command: "npx"
args: ["-y", "mcp-genoffice"]
env:
# optional: point at your own genoffice clone; otherwise the server
# auto-clones the pinned revision into ~/.cache/mcp-genoffice/src
# GENOFFICE_SRC: "/path/to/genoffice"
timeout: 300
connect_timeout: 120How the engines are loaded
The GenOffice engine packages are not published to npm and ship as
TypeScript source. The server loads them from a checkout of
genspark-ai/genoffice in two ways:
GENOFFICE_SRCenv var — use your own clone (fast, dev mode).Auto-clone (default) — a shallow, SHA-pinned checkout (
GENOFFICE_PINinsrc/engine.ts) plusnpm installon first use.
The server runs under the tsx loader so the TS-source engines import cleanly.
Development
npm install
npx tsc --noEmit # typecheck
node tests/client.mjs # end-to-end: spawns the server, lists tools, patches a fixtureThe e2e test uses fixture files from a genoffice clone. By default it points at
/tmp/genoffice; override with FIXTURE_SRC. Unset SERVER_SRC to exercise
the auto-clone path.
Roadmap
Headless engine mode (extract + docx blocks + docx patch)
genoffice_docx_patchrich options (styles, headers, comments, watermark)PPTX / XLSX tools (pptx-engine, sheets sidecar)
CDP mode: drive the installed GenOffice app (launch, open file, AI edit)
Hermes MCP catalog entry (
optional-mcps/genoffice) + usage skill
License
MIT. The GenOffice engine packages are Apache-2.0 (loaded at runtime from a user-provided or auto-cloned checkout, never bundled).
Available Tools
15 toolsgenoffice_app_evalGenOffice app eval (DOM)A
Evaluate a JavaScript expression in the GenOffice app page context over CDP (DOM reads/writes). Read-only by default (mutate=true required to change the page). Use for inspecting UI state that the read tools do not cover. Requires the app running with the debug port.
Inputs: expression (required), mutate.
genoffice_app_launchGenOffice app launch (CDP)A
Launch the installed GenOffice app with the CDP debug port open so the agent can drive it (screenshots, DOM evaluation). If the app is already running WITHOUT the debug port, it is terminated first (single-instance lock would otherwise swallow the relaunch) — set killExisting=false to abort instead. Handles the auto-updater relaunch by retrying until the port answers. macOS uses open -a; other platforms launch the binary.
Inputs: killExisting.
genoffice_app_open_fileGenOffice app open fileA
Open an Office/PDF file in the GenOffice desktop app via the macOS open command (the app registers .docx/.xlsx/.pptx/.pdf document types). The app does not need to be running with CDP for this — it launches normally. macOS only.
Inputs: path (required).
genoffice_app_screenshotGenOffice app screenshotA
Capture a PNG screenshot of the GenOffice app window over CDP and save it to outPath. Requires the app running with the debug port (genoffice_app_launch). Use together with vision to inspect the current UI state.
Inputs: outPath (required).
genoffice_app_statusGenOffice app statusA
Check whether the GenOffice desktop app is installed and whether its CDP debug port is up. Returns the app bundle version, the running process version (when the debugger is live) and the current page title/url. Read-only; does not launch anything.
Inputs: no named parameters.
genoffice_docx_blocksGenOffice docx blocksA
Parse a .docx with the GenOffice engine and list its top-level blocks (paragraphs/headings/tables) with their index, type, style and text. Use this BEFORE genoffice_docx_patch to pick the block indexes you want to rewrite.
Inputs: path (required).
genoffice_docx_createGenOffice docx createA
Create a NEW .docx from scratch using the GenOffice engine (buildBlankDocx). Optionally pass paragraphs (each string becomes one paragraph; use \n inside a string for line breaks within the same paragraph). Writes the file to outPath.
Inputs: outPath (required), paragraphs.
genoffice_docx_deleteGenOffice docx delete blocksA
Delete one or more top-level blocks (paragraphs/headings) from a .docx using the GenOffice byte-preserving roundtrip: the deleted blocks are spliced out, all remaining blocks keep their original bytes. Indexes come from genoffice_docx_blocks (0-based visible order). Writes a NEW file.
Inputs: path (required), indexes (required), outPath.
genoffice_docx_patchGenOffice docx patch (byte-preserving)A
Rewrite one or more paragraphs of a .docx using the GenOffice byte-preserving roundtrip: only the edited blocks are regenerated as OOXML fragments; every untouched block keeps its original bytes, so layout, styles, headers, comments and other parts survive. Paragraph formatting (styleId/rawPPr) is carried over. Input: file path + edits [{index, text}] where index comes from genoffice_docx_blocks (0-based visible order). Output: a new patched file (never modifies the original).
Inputs: path (required), edits (required), outPath.
genoffice_docx_watermarkGenOffice docx watermarkA
Set a text watermark on a .docx using the GenOffice engine: the header part is regenerated with the watermark paragraph while the document body keeps its original bytes (byte-preserving roundtrip). Pass an empty string to remove the watermark. Writes a NEW file, never modifies the original.
Inputs: path (required), text (required), outPath.
genoffice_extract_textGenOffice extract textA
Extract readable text from an Office or PDF file using GenOffice engines (docx/xlsx/pptx/pdf). Returns the document content as markdown-ish text with slide/table structure. Use this to read the content of a document before editing it.
Inputs: path (required).
genoffice_pptx_createGenOffice pptx createA
Create a NEW .pptx from scratch using the GenOffice engine (createBlankPptx): a deck with one blank slide. Use genoffice_pptx_patch afterwards to fill in titles and content. Writes the file to outPath.
Inputs: outPath (required).
genoffice_pptx_deleteGenOffice pptx delete elementsA
Delete one or more text/shape elements from a slide of a .pptx using the GenOffice engine (element-level byte-preserving: the edited slide is rebuilt, every other slide and zip part keeps its original bytes). Elements are matched by name or id from genoffice_pptx_slides. Writes a NEW file.
Inputs: path (required), slide (required), elements (required), outPath.
genoffice_pptx_patchGenOffice pptx patch (byte-preserving)A
Replace the text of one or more text elements on a slide of a .pptx, using GenOffice element-level byte-preserving patching: only the edited elements are regenerated; every untouched element and zip part keeps its original bytes. The first run/paragraph of each element is used as the formatting template (font, size, color, alignment, bullets survive). Multi-line text with \n creates one paragraph per line. Writes a NEW file, never modifies the original.
Inputs: path (required), edits (required), slide (required), outPath.
genoffice_pptx_slidesGenOffice pptx slidesA
Open a .pptx with the GenOffice engine and list every slide with its text elements (id, name, type, text preview). Use this BEFORE genoffice_pptx_patch to identify which slide and element to edit.
Inputs: path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
The file-based tools (docx/pptx) are clearly separated by format and operation (create/patch/delete/blocks/slides), and the app-control tools are distinct from file tools. There is minor potential confusion between genoffice_docx_patch and genoffice_docx_delete, and between genoffice_extract_text and genoffice_docx_blocks (both read content), but descriptions are detailed enough to disambiguate.
All tools follow a consistent genoffice_<domain>_<verb> pattern, with domains (docx, pptx, app) and verbs (create, patch, delete, status, launch) applied consistently. No camelCase mixing or irregular verb styles. The pattern is highly predictable.
15 tools is at the upper boundary of the well-scoped range but reasonable given the server covers both file manipulation (8 tools) and app control (5 tools) plus shared extraction. Each tool earns its place for distinct operations.
The server provides solid lifecycle coverage for docx and pptx (create, read, patch, delete) plus extract_text for cross-format reading and app control tools. Minor gaps include no xlsx-specific editing tools despite xlsx being mentioned in extraction, no pptx slide reordering, and no docx block insertion (only rewrite/delete).
Maintenance
Related MCP Connectors
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Generate, edit, merge, translate and PDF-convert PowerPoint (.pptx) over MCP. 8 tools.
Document processing over MCP: merge, split and compress PDFs, run OCR, extract document text.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server for reading, editing, and validating Microsoft Word documents with specialized support for track changes, comments, and footnotes. It enables structural auditing, heading extraction, and precise OOXML-level document manipulation through natural language tools.101001,196 PyPI69MIT
- FlicenseAqualityCmaintenanceMCP server for Microsoft Office file operations. Read, write, and create Excel, Word, and PowerPoint files directly from your local filesystem.12-
- AlicenseCqualityDmaintenanceA unified MCP server for document processing that enables creating, editing, and converting Word documents (DOCX), PDFs, Markdown, and images, with support for templates, formatting, and batch operations.100MIT
- AlicenseAqualityDmaintenanceMCP server for rendering, parsing, converting, and editing Office documents (Excel, PowerPoint, Word) from a structured JSON spec, using LibreOffice WASM for conversion and preview.51ISC