WordMcp — Microsoft Word MCP-Server

Ein MCP-Server, der KI-Assistenten dabei hilft, Microsoft Word für Windows über COM-Automatisierung zu steuern: Dokumente öffnen, Text lesen und bearbeiten, Absätze und Tabellen verwalten, Dokumenteigenschaften festlegen und als PDF exportieren.

Nur Windows. Eine lokale Installation von Microsoft Word ist erforderlich. Dieser Server automatisiert die echte Anwendung, er parst keine .docx-Dateien.

Anforderungen

Related MCP server: Word Document MCP Server

Installation

dotnet tool install --global WordMcp.McpServer

Das Tool ist danach als mcp-word verfügbar.

mcp-word --version
mcp-word --help

Um es später zu aktualisieren oder zu entfernen:

dotnet tool update --global WordMcp.McpServer
dotnet tool uninstall --global WordMcp.McpServer

Um stattdessen einen unveröffentlichten Build auszuführen, packen Sie ihn lokal und installieren Sie ihn aus dem Ausgabeordner:

dotnet pack src\WordMcp.McpServer\WordMcp.McpServer.csproj -c Release -o artifacts
dotnet tool install --global --add-source .\artifacts WordMcp.McpServer

Ohne Installation

Der Server ist im MCP-Registry als io.github.trsdn/mcp-server-word gelistet. Clients, die Pakete selbst auflösen, können ihn über dnx ausführen, das die Version bei Bedarf abruft, statt ein globales Tool vorzuhalten:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "dnx",
      "args": ["WordMcp.McpServer@0.1.0", "--yes"]
    }
  }
}

Client-Konfiguration

Der Server spricht stdio.

VS Code / GitHub Copilot

.vscode/mcp.json:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "mcp-word"
    }
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "word": {
      "command": "mcp-word"
    }
  }
}

Copilot CLI

copilot mcp add word --command mcp-word

Konzepte

Jeder Vorgang läuft innerhalb einer Sitzung. Eine Sitzung besitzt eine Word-Instanz und ein geöffnetes Dokument, identifiziert durch eine session_id wie word-a1b2c3d4e5f6g.

file(open|create) ──► session_id ──► text / paragraph / table / document ──► file(save) ──► file(close)

• Pfade müssen absolut sein (C:\Users\me\Documents\report.docx).

• Unterstützte Eingabeformate: .docx, .docm, .doc, .dotx, .dotm, .rtf.

• Das Dokument darf nicht bereits in Word geöffnet sein – WordMcp benötigt exklusiven Zugriff.

• Word läuft unsichtbar im Hintergrund und wird beendet, wenn die Sitzung geschlossen wird.

Der Sitzungsdienst

Sitzungen leben normalerweise im Prozess des MCP-Servers und verschwinden mit ihm. WordMcp.Service.exe ist ein optionaler Hintergrund-Daemon, der die Sitzungen stattdessen hält, sodass eine Sitzung einen Client-Neustart übersteht und von mehreren Clients gemeinsam genutzt werden kann:

WordMcp.Service.exe --daemon [--idle-minutes 30]   # listen until idle or stopped
WordMcp.Service.exe --status                       # what is it doing?
WordMcp.Service.exe --stop                         # save open documents and exit

Ein manueller Start ist selten nötig – ein Client, der den Daemon nutzt, startet ihn bei Bedarf. Die Pipe, auf der er lauscht, enthält Ihre SID und ist per ACL an diese gebunden, sodass Sitzungen nie zwischen Konten geteilt werden. Er beendet sich von selbst, sobald nach dem Leerlauf-Timeout keine Sitzung mehr geöffnet war.

Um den Daemon zu verwenden, setzen Sie für den MCP-Server WORDMCP_SERVICE_MODE=daemon. Jeder Tool-Aufruf wird dann an den Daemon gesendet, statt im eigenen Prozess des Servers zu laufen. Ohne diese Einstellung behält der Server die Sitzungen für sich selbst – genau das, was ein einzelner Client möchte: kein zweiter Prozess und keine Wartezeit beim Start.

Tools

Fünfzehn Tools, jeweils mit einem action-Parameter.

file — Sitzungslebenszyklus

file(action: "open", path: "C:\\Users\\me\\Documents\\report.docx")
// → { "sessionId": "word-a1b2c3d4e5f6g", "fileName": "report.docx", ... }

text — Inhalt

Zeichenpositionen stammen aus get und find und sind Word-Range-Offsets.

paragraph — Absätze

Absatzindizes sind 1-basiert, genau wie in Word.

table — Tabellen

document — Metadaten und Export

image — Bilder

field — Felder und Inhaltsverzeichnisse

section — Abschnitte und Seiteneinrichtung

header-footer — Kopf- und Fußzeilen

kind wählt header oder footer aus, type wählt primary, first-page oder even-pages aus.

style — Formatvorlagen

style_type wählt paragraph, character, table oder list. Übergeben Sie in_use_only: false an list, um den vollständigen Satz einer lokalisierten Word-Version zu erhalten, der über 370 Einträge umfasst.

style(action: "create", session_id: "...", name: "Callout", base_style: "Normal")
style(action: "modify", session_id: "...", name: "Callout",
      font_size: 11, bold: true, color: "#C00000", space_after: 12)

list — Aufzählungen und Nummerierung

Ohne end_index wird die Aktion ausschließlich auf start_index angewendet.

list(action: "apply", session_id: "...", start_index: 2, end_index: 5, list_type: "number")
list(action: "set-level", session_id: "...", start_index: 3, end_index: 4, level: 2)
list(action: "restart", session_id: "...", start_index: 6)

comment — Kommentare

add kommentiert den gesamten Absatz, es sei denn, anchor_text benennt eine Phrase darin. Indizes von Unterschieden nach delete – listen Sie die Kommentare vor dem Löschen eines weiteren Kommentars also erneut auf.

comment(action: "add", session_id: "...", paragraph_index: 4,
        text: "Source?", anchor_text: "fifteen percent")
comment(action: "list", session_id: "...", unresolved_only: true)

revision — Änderungen nachverfolgen

Wenn bei accept/reject der index weggelassen wird, wird das gesamte Dokument behandelt, einschließlich Kopf- und Fußzeilen.

revision(action: "set-tracking", session_id: "...", enabled: true)
revision(action: "accept", session_id: "...")

bookmark — stabile Verweise

Namen müssen mit einem Buchstaben beginnen und dürfen nur Buchstaben, Ziffern und Unterstriche enthalten. Lesezeichen überstehen Bearbeitungen an anderer Stelle des Dokuments und sind deshalb der zuverlässige Weg, auf eine Textstelle zu verweisen, sobald sich die Absatzindizes verschoben haben.

bookmark(action: "add", session_id: "...", name: "Intro", paragraph_index: 2)
bookmark(action: "add", session_id: "...", name: "Growth",
         paragraph_index: 4, anchor_text: "fifteen percent")
bookmark(action: "get-text", session_id: "...", name: "Intro")

screenshot — die Seite anzeigen

Layoutfragen — Seitenumbrüche, Tabellenbreiten, Bildplatzierung, Kopfzeilenpositionen — lassen sich anhand der gerenderten Seite weitaus leichter beantworten als aus. Das PNG wird in eine Datei geschrieben und der Pfad zurückgegeben; include_image: true gibt es zusätzlich inline als base64 zurück, was nur dann den Kontext lohnt, wenn das Bild auch angesehen werden soll.

dpi hat den Standardwert 150. Verwenden Sie 96 für eine schnelle Layoutprüfung und 300 für etwas in druckähnlicher Qualität.

screenshot(action: "page", session_id: "...", page: 2)
screenshot(action: "page", session_id: "...", page: 1,
           output_path: "C:/temp/page1.png", dpi: 300, include_image: true)

Antworten

Jedes Tool gibt JSON zurück. Fehler werden als strukturierte Antworten gemeldet, niemals als Transportfehler:

{
  "success": false,
  "isError": true,
  "tool": "text",
  "action": "Replace",
  "errorType": "KeyNotFoundException",
  "errorMessage": "Session 'word-unknown' not found."
}

Bekanntes Verhalten und Fallstricke

• document(save-as) speichert auch das Original. Word hat keine API, die das Format ändert, indem sie eine Kopie speichert. Für jedes andere Ziel außer PDF ruft der Server SaveAs2(target) und dann SaveAs2(original) auf, was ausstehende Änderungen als Nebeneffekt in der Originaldatei speichert. Verwenden Sie export-pdf, wenn Sie einen Export ohne Nebenwirkung brauchen.

• Farben sind hex-RGB (#0078D4). Der Server konvertiert in den BGR-Wert, den Word erwartet.

• Rechtegeschützte Dokumente (IRM/AIP) werden abgelehnt, bevor Word gestartet wird.

• Ein Dokument, das in Word geöffnet ist, blockiert die Sitzung — schließen Sie es zuerst.

• Word-Dialoge blockieren die Automatisierung. Wenn ein Aufruf eine Zeitüberschreitung hat, prüfen Sie zuerst, ob auf dem Desktop ein Dialog geöffnet ist.

• Formatnamen sind englisch. Integrierte Formate (Heading 1, Title, Table Grid, …) werden in die Sprachklärung „ – deutschen Stil-IDs von Word übersetzt, sodass sie auf lokalisierten Installationen funktionieren. Jeder andere Name wird unverändert an Word übergeben; so werden benutzerdefinierte und lokalisierte Stile angesprochen. Beachten Sie: Word meldet Stile unter ihrem lokalisierten Namen (Überschrift 1 auf einer deutschen Installation). Darum gibt style(list) sowohl name als auch english_name zurück — senden Sie english_name zurück, wenn er vorhanden ist.

• Integrierte Stile können nicht gelöscht werden. style(delete) lehnt das klar verständlich ab, anstelle des generischen COM-Fehlers von Word durchzusickern. Auch ein benutzerdefinierter Stil, der in einer Textmarke noch auf einen Absatz angewendet wird, kann nicht gelöscht werden; setzen Sie diese Absätze zuerst auf einen anderen Stil.

• Neue Dokumente werden direkt geschrieben, nicht über Word. file(create) schreibt selbst eine leere ..docx/.docm`-Paket-Paketdatei und öffnet sie. Dokumente über Word zu erstellen, ist auf Computern mit Microsoft-365-Anmeldung unzuverlässig, weil AutoSave das neue Dokument für OneDrive beansprucht und den anforderten lokalen Pfad stillschweigend ignoriert.

• Zusammengefügte Tabellenzellen werden von table(read) als leere Zeichenketten zurückgegeben.

• Bildgrößen sind Maßeinheit Punkt, nicht Pixel (72 pt = 1 Zoll). image(insert) und image(resize) erhalten das Seitenverhältnis, außer gesetzt ist; wird nur width übergeben, wird die Höhe automatisch skaliert.

• image umfasst nur Inline-Bilder. Schwebende Objekte, Textfelder und Diagramme werden unberührt bleiben und erscheinen nicht in image(list); ihre Anwesenheit verschiebt also nicht die Bildindizes.

• Ein Inhaltsverzeichnis listet nur Überschriftenabsätze auf. field(insert-toc) liefert entry_count: 0 für ein Dokument ohne Überschriftenstile — wenden Sie zuerst Heading 1/Heading 2 über paragraph(add|set-style) an, dann rufen Sie field(update-toc) aus.

• field(update-all) erfasst auch Kopf- und Fußzeilen. Wenn Document.Fields von Word nur den Textkörper abdeckt, warum beziehen sich Seitenzahlen eigentlich sonst verschieden s? Deshalb würden Seitenzahlen nie aktualisiert, wenn dieser nicht mitbehandelt würde.

• image(insert) mit einer Beschriftungsanmerkung verwendet die Nummerierung von „Beschriftung“ in Word, sodass die Bildunterschrift Figure 1 <Ihr_text> lautet (auf nicht-englischen Installationen lokalisiert) und an einem Abbildungsverzeichnis teilnimmt.

• Alle Maße sind in Punkt gehalten, einschließlich Seiten enthält; Abbildung (1 cm = 28,35 pt; 1 Zoll = 72 pt).

• section(page-setup) formiert paper_size vor den Rändern, weil die Änderung der Papiergröße die Ränder im Word zurücksetzt. Ohne section_index gilt das für alle Abschnitte.

• Spalten- und Fußzeilen werden zwischen Abschnitten vererbt. Ein neuer Abschnitt zeigt die Kopfzeile des vorherigen Abschnitts, bis etwas hineingeschrieben wird. header-footer(set) mit Angabe einer section_index unterbricht die Verknüpfung automatisch, in Abschnitt 1 bleibt also sein eigener Text erhalten.

• first-page und even-pages brauchen einen Abschnittswechsel. header-footer(set) aktiviert für Sie DifferentFirstPage bzw. DifferentOddEvenPages — ohne das speichert Word Speichert den Text, rendert ihn aber nie.

• list(apply) startet standardmäßig eine neue Liste. `` weiter: continue_previous_list ist aus, da eine Übernahme der Nummerung einer unzusammenhängenden früheren Liste selten beabsichtigt ist. Zwei nummerierte Listen, die mit normalen Absätzen getrennt sind, bleiben getrennt; verwenden Sie list(restart), falls Word sie trotzdem zusammenfügt.

• Nur das Listenformatete mit Ebenen von Gliedern zeigt Ebenen mit unterschiedlichen Graden. list(set-level) funktioniert mit jeder Liste, aber eine einfache bullet- oder number-Liste zeigt auf jeder Ebene denselben Marker — die Absätze sind gleichsam nur noch eingerückt.

• comment(resolve) schlägt bei Microsoft 365 oft fehl. Moderne Kommentare in Word behandeln jeden über die API hinzugefügten Kommentar als unveröffentlichten Entwurf, und Entwürfe können nicht als erledigt markiert werden. Der Server meldet das benaberzield klar; löschen Sie den Kommentar stattdessen. comment(list) liefert resolved: null auf Systemen, die den Zustand überhaupt nicht offengeben.

• Kommentar- und Revisions-Indizes verschieben sich. Das Löschen von Kommentaren oder das Annehmen einer einzelnen überarbeitung nummeriert alles danach neu. Führen Sie vor, zäh Tor. BetweenZwei solchen Aufrufen: Führen Sie list erneut aus, statt die alten Indizes zu verwenden.

• revision(accept|reject) ohne Indexursor umfasst auch Kopf- und Fußzeilen. Word Document.AcceptAllRevisions() deckt nur den Textkörper ab, genau dieselbe Lücke wie bei field(update-all).

• Verfolgte Änderung werden nur aufgezeichnet, solange Überarbeitungen getrackt werden. revision(set-tracking) wirkt nicht retentional— aktivieren Sie die. Bevor Sie die Änderungen durchführen, die Sie aufgezeichnet haben möchten.

• Lesezeichennamen unterliegen Einschränkungen aus Word. Sie müssen mit einem Buchstaben beginnen, dürfen nur Buchstaben, Ziffern und Unterstriche enthalten und sind auf 40 Zeichen begrenzt. Leerzeichen, Bindestriche, Punkte und nicht-ASCII-Buchstaben werden abgelehnt, bevor der Aufruf Word erreicht, das sonst mit einem generischen COM-FehlFehler abbricht.

• Lesezeichen Lesezeichen sind der stabile Weg, um auf eine Passage zu verweisen. Die Absatzindexe a ändern sich bei jedem Einfügen, Buchzeichen nicht. Diese Stelle Lesezeichen zuerst aus und lesen Sie später mit bookmark(get-text) wieder.

• bookmark(add) auf einem Absatz schließt Paragraph-Zeichenzeichen aus, sodass get-text den Text ohne nachfolgenden Zeilenumbruch zurückgibt. Ein Lesezeichen über mehrere Absätze enthält die Zeichen dazwischen.

• screenshot(page) rendert über eine PDF. Word hat keine API, die eine Art als Bild liefert; der Server export die Einzelseite mit ExportAsFixedFormat und wandelt sie in Raster. Ungespeicherte Änderungen werden ein begonnenessen, und die temporäre PDF wird danach gelöscht.

• Seitenzahlen stammen aus neuer Rerepagination. Ein Dokument, das nur automatisiert bearbeitet wird, meldet eine überholte Seitenzahl; deshalb macht screenshot zuerst eine neue Seitenwanderung. Das bedeutet, dass die Seitenzahl den aktuellen Layout repr en wiring repulsiert, nicht das beim Öffnen.

Bau aus dem Quellcode

git clone https://github.com/trsdn/mcp-server-word.git
cd mcp-server-word
dotnet build WordMcp.sln -c Release
dotnet test WordMcp.sln --filter "Category!=RequiresWord"

Projekteinrichtung

Generierte Werkzeugschicht

Vierzehn Aufgaben der fünfzehn Tools werden zur Build-Zeit erzeugt. Die Befehl- und Schnittstellen in src/WordMcp.Core/Commands sind die genaue Spezifikation für den Vertrag:

• ServiceCategory( "section", "Section") benennt die Tool-Klasse, WordSectionTool.

• [McpTool("section", Title = ..., Description = ...)] liefert den ToolNamen und den Prompt, dem das Modell liest.

• [ServiceAction("page-setup")] auf jeder Methode wird zu einem Enum-Wert der generierten WordSectionAction.

• XML-Dokumentation der Schnittstellenparameter wird zu den Parameterbeschreibungen im MCP-Schema.

Der Generator führt die Parameter aller Aktionen in einer Methode, so dass ein param Parameter, der nur von einigen Aktionen verwendet wird, als optional oll als ausgegeben wird. Für die API-Änderung arbeiten Sie die Schnittstelle — und niemals generierten Code berühren. file bleibt von Hand geschrieben, weil es Sitzungen verwaltet, nicht mit jeweilsArbe una-bearbeitet.

Unter src/WordMcp.McpServer/obj/gen steht der erzeugten Code. Die Tests im GeneratedToolContractTests vergleichen die generierte Oberfläche mit den Schnittstellen, so dass eine Abweichung den Build fehlschlagen lassen, statt bis zum Client zu gelangen.

Tests, die eine echte Word-Installation benötigen, werden mit [Trait("Category", "RequiresWord")] markiert und in CI ausgeschartet.

Fehlgeschlagene Integrationstests können verwaiste WINWORD.EXE-Prozesse zurücklassen, die spätere Läufe verlangsamen oder blockieren können. Räumen Sie sie auf mit GetProcess WINWORD | Stop-Process -Force, bevor Sie neu starten.

Weiterführende Informationen

Troubleshooting

Mitwirken

Fehlermeldungen und Feature-Wünsche lassen sich über die Issue-Vorlagen einreichen. Pull-Requests sind willkommen; CONTRIBUTING.md beschreibt, wie das Projekt gebaut wird, wie die beiden Hälften der Testsuite ausgeführt werden und was erforderlich ist, um ein Tool hinzuzufügen.

Bitte lesen Sie zuerst den Code of Conduct.

Reichen Sie für ein Sicherheitsproblem kein öffentliches Issue ein — melden Sie es privat, wie in der Sicherheitsrichtlinie beschrieben.

Lizenz

MIT — siehe LICENSE.