DOCX MCP Server

Universeller DOCX-Verarbeitungsserver, der das Model Context Protocol (MCP) mit vollständiger OOXML-Unterstützung implementiert.

Funktionen

• Vollständige OOXML-Unterstützung: Lesen/Schreiben aller DOCX-Dokumentteile (document.xml, Styles, Numbering, Kopf-/Fußzeilen usw.)

• Textoperationen: Text extrahieren, suchen und ersetzen mit wörtlichem oder Regex-Modus

• Tabellenbearbeitung: Zeilen/Spalten einfügen/löschen, Zellen zusammenführen, Zellinhalt festlegen

• Strukturierte Daten-Tags (SDT): Inhaltssteuerelemente nach Tag oder Alias abrufen/festlegen

• Bilder: Bilder auflisten, Inline- oder verankerte Bilder mit Positions-/Größensteuerung einfügen

• Kommentare & Änderungen: Kommentare auflisten, hinzufügen/löschen, alle nachverfolgten Änderungen übernehmen

• Dokumenteigenschaften: Metadaten lesen/schreiben (Titel, Autor, Betreff usw.)

• LRU-Caching: Speichereffizientes Caching von Dokumentteilen

• Stdio-Transport: MCP-Kommunikation über stdin/stdout

Installation

npm install
npm run build

Ausführung

Entwicklung

npm run dev

Produktion

npm start

Mit Claude Code

claude mcp add --scope user --transport stdio docx -- node /path/to/dist/index.js

Werkzeuge

Dokumentverwaltung

docx.open

Öffnen eines DOCX-Dokuments aus Datei oder Base64

{
  "docId": "uuid",
  "parts": ["word/document.xml", "word/styles.xml", ...],
  "partCount": 42,
  "props": { "core": {...}, "app": {...} }
}

docx.close

Schließen und Entladen eines Dokuments

docx.save

Speichern des Dokuments in eine Datei oder Rückgabe als Base64

Teilverwaltung

docx.list_parts

Alle Teile im Dokument auflisten

docx.part_read

Rohes XML eines bestimmten Teils lesen

docx.part_write

XML-Inhalt eines Teils schreiben/aktualisieren

Textoperationen

docx.get_text

Gesamten Text aus dem Dokument extrahieren

{
  "docId": "uuid",
  "scope": "document" | "headers" | "footers" | "all"
}

docx.find

Text mit Kontext suchen

{
  "docId": "uuid",
  "query": "search term",
  "mode": "literal" | "regex"
}

docx.replace_text

Text im Dokument ersetzen

{
  "docId": "uuid",
  "match": "old text",
  "replace": "new text",
  "mode": "literal" | "regex"
}

Tabellen

docx.tables_list

Alle Tabellen mit Abmessungen auflisten

{
  "tables": [
    {
      "xpath": "/w:document/w:body/w:tbl[1]",
      "rows": 3,
      "colsApprox": 4
    }
  ]
}

docx.table_edit

Tabellenstruktur und -inhalt ändern

{
  "docId": "uuid",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": {
    "kind": "setCellText",
    "row": 0,
    "col": 1,
    "text": "new value"
  }
}

Operationen:

• setCellText(row, col, text) – Zellinhalt festlegen

• insertRow(at) – Zeile an Position einfügen

• deleteRow(at) – Zeile löschen

• insertCol(at) – Spalte einfügen

• deleteCol(at) – Spalte löschen

Strukturierte Daten (SDT)

docx.sdt_get

Inhalt eines Inhaltssteuerelements nach Tag oder Alias abrufen

docx.sdt_put

Inhaltssteuerelement aktualisieren

Bilder

docx.images_list

Alle Bilder mit Metadaten auflisten

docx.image_add

Bild inline oder verankert einfügen

Stile & Nummerierung

docx.styles_get / docx.styles_set

styles.xml lesen/schreiben

docx.numbering_get / docx.numbering_set

numbering.xml lesen/schreiben

Kopf-/Fußzeilen

docx.headers_footers_list

Alle Kopf-/Fußzeilenteile auflisten

Kommentare

docx.comments_list

Alle Kommentare auflisten

docx.comments_add

Neuen Kommentar hinzufügen

docx.changes_accept_all

Alle nachverfolgten Änderungen im Dokument übernehmen

Metadaten

docx.metadata_get

Dokumenteigenschaften abrufen (Titel, Autor, Erstellt, Geändert usw.)

Testszenarien

1. Grundlegendes Lesen/Schreiben

# Open document
docx.open: { "path": "/path/to/document.docx" }

# Get text
docx.get_text: { "docId": "returned-id" }

# Replace text
docx.replace_text: {
  "docId": "returned-id",
  "match": "old text",
  "replace": "new text"
}

# Save
docx.save: { "docId": "returned-id", "returnBase64": true }

2. Tabellenmanipulation

# List tables
docx.tables_list: { "docId": "id" }

# Edit cell
docx.table_edit: {
  "docId": "id",
  "tableXPath": "/w:document/w:body/w:tbl[1]",
  "op": { "kind": "setCellText", "row": 0, "col": 0, "text": "Hello" }
}

3. Bilder

# List images
docx.images_list: { "docId": "id" }

4. Nachverfolgte Änderungen

# Accept all changes
docx.changes_accept_all: { "docId": "id" }

Architektur

src/
  index.ts                    # Entry point
  errors.ts                   # Error definitions
  logger.ts                   # Logging utilities
  ooxml/
    namespaces.ts            # XML namespace definitions
    emu.ts                    # EMU conversion utilities
    dom.ts                    # XML DOM utilities (xmldom + fontoxpath)
    xmlParser.ts              # fast-xml-parser wrapper
    parts.ts                  # DOCX ZIP part management
    rels.ts                   # Relationships management
    text.ts                   # Text extraction & replacement
    tables.ts                 # Table operations
    sdt.ts                    # Structured Data Tags
    drawings.ts               # Images & DrawingML
    headersFooters.ts         # Headers/Footers
    styles.ts                 # Style operations
    numbering.ts              # Numbering operations
    changes.ts                # Track changes
    comments.ts               # Comments
  store/
    types.ts                  # Type definitions
    docStore.ts               # Document store + LRU cache
  mcp/
    schemas.ts                # Tool input schemas
    tools.ts                  # Tool implementations
    server.ts                 # MCP server setup

Abhängigkeiten

• @modelcontextprotocol/sdk – MCP-Implementierung

• jszip – ZIP-Archivverarbeitung

• fast-xml-parser – Verlustfreies XML-Parsing

• @xmldom/xmldom – DOM-Implementierung

• fontoxpath – XPath-Abfragen

• diff-match-patch – Text-Diffing

• lru-cache – Speichereffizientes Caching

• uuid – Dokument-ID-Generierung

Leistungshinweise

• Dokumente bis zu 10 MB werden unterstützt

• LRU-Cache mit 100-Teile-Limit und 1 GB Speichergrenze

• Teile werden bei Bedarf geladen, nicht vollständig in den Speicher

• Dirty-Part-Optimierung: Nur geänderte Teile werden in ZIP gespeichert

• Kein tiefes Kopieren von XML-Strukturen

Einschränkungen

• Kopf-/Fußzeilen: Grundlegende Unterstützung (komplexe Abschnittsstrukturen können manuelle Anpassungen erfordern)

• Kommentare: Grundlegende Liste/Hinzufügen/Löschen (Antwortketten werden nicht vollständig unterstützt)

• Nachverfolgte Änderungen: Alle übernehmen verfügbar; detaillierte Änderungsprüfung eingeschränkt

• Stile: Vollständiges XML abrufen/festlegen; keine selektive Stilzusammenführung

• EMU/Größen: Berechnet, aber gerenderte Geometrie hängt von der Layout-Engine von Word ab

Lizenz

MIT