Skip to main content
Glama

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

genoffice_extract_text

Extract readable text from .docx / .xlsx / .pptx / .pdf (slides/table structure preserved)

genoffice_docx_blocks

Parse a .docx and list top-level blocks (index, type, style, text)

genoffice_docx_patch

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

genoffice_docx_watermark

Set/remove a text watermark (header regenerated, body byte-preserved)

genoffice_docx_create

Create a NEW .docx from scratch (optional initial paragraphs, each with optional formatting)

genoffice_docx_delete

Delete blocks (paragraphs/headings) — remaining blocks byte-preserved

genoffice_pptx_slides

List slides and their text elements (id, name, type, text)

genoffice_pptx_patch

Replace text of elements on a slide (element-level byte-preserving); optional formatting per edit (bold/italic/color/sizePt/font)

genoffice_pptx_create

Create a NEW .pptx from scratch (one blank slide)

genoffice_pptx_delete

Delete elements from a slide (other slides/parts byte-preserved)

genoffice_app_status

GenOffice desktop app: installed? CDP port up? (read-only)

genoffice_app_launch

Launch the app with the CDP debug port (handles auto-update relaunch)

genoffice_app_open_file

Open a file in the app (macOS open -a, registered doc types)

genoffice_app_screenshot

PNG screenshot of the app window over CDP

genoffice_app_eval

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-genoffice

Configure 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: 120

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

  1. GENOFFICE_SRC env var — use your own clone (fast, dev mode).

  2. Auto-clone (default) — a shallow, SHA-pinned checkout (GENOFFICE_PIN in src/engine.ts) plus npm install on 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 fixture

The 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_patch rich 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 tools
genoffice_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

    A4.1/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers