docx-mcp

Open a .docx file for reading and editing.

Unpacks the DOCX archive, parses all XML parts, and caches them in memory. Only one document can be open at a time; opening a new one closes the previous.

Args: path: Absolute path to the .docx file.

Close the current document and clean up temporary files.

Get overview stats: paragraph count, headings, footnotes, comments, images.

Get the document heading structure with levels, text, and paraIds.

Returns a list of headings in document order, each with:

• level (1-9)

• text (heading content)

• style (e.g., "Heading1")

• paraId (unique paragraph identifier for targeting edits)

Search for text across the document body, footnotes, and comments.

Args: query: Text to search for (case-insensitive), or a regex pattern. regex: If true, treat query as a Python regular expression.

Returns matching paragraphs with their paraId, source part, and context.

Get the full text and style of a specific paragraph by its paraId.

Args: para_id: The 8-character hex paraId (e.g., "1A2B3C4D").

List all footnotes with their ID and text content.

Add a footnote to a paragraph.

Creates the footnote definition in footnotes.xml and adds a superscript reference number at the end of the target paragraph.

Args: para_id: paraId of the paragraph to attach the footnote to. text: Footnote text content.

Cross-reference footnote IDs between document.xml and footnotes.xml.

Checks that every footnote reference in the document body has a matching definition, and flags orphaned definitions with no reference.

Check paraId uniqueness across all document parts.

ParaIds must be unique across document.xml, footnotes.xml, headers, footers, and comments. They must also be valid 8-digit hex values < 0x80000000.

Remove VML watermarks (e.g., DRAFT) from all document headers.

Detects and removes <v:shape> elements with <v:textpath> inside header XML files — the standard pattern for Word watermarks.

Run a comprehensive structural audit of the document.

Checks:

• Footnote cross-references (references vs definitions)

• ParaId uniqueness and range validity

• Heading level continuity (no skips like H2 -> H4)

• Bookmark pairing (start/end matching)

• Relationship targets (all referenced files exist)

• Image references (all embedded images exist)

• Residual artifacts (DRAFT, TODO, FIXME markers)

Returns a detailed report with an overall valid/invalid status.

Insert text with Word track-changes markup (appears as a green underlined insertion in Word).

Args: para_id: paraId of the target paragraph. text: Text to insert. position: Where to insert — "start", "end", or a substring to insert after. author: Author name for the revision (shown in Word's review pane).

Mark text as deleted with Word track-changes markup (appears as red strikethrough in Word).

Finds the exact text within the paragraph and wraps it in deletion markup. The text must exist within a single run (formatting span).

Args: para_id: paraId of the target paragraph. text: Exact text to mark as deleted. author: Author name for the revision.

List all comments with their ID, author, date, and text.

Add a comment anchored to a paragraph.

Creates the comment in comments.xml and adds range markers (commentRangeStart/End) around the paragraph content.

Args: para_id: paraId of the paragraph to comment on. text: Comment text. author: Author name (shown in Word's comment sidebar).

Reply to an existing comment (creates a threaded reply).

Args: parent_id: ID of the comment to reply to. text: Reply text. author: Author name.

Save all changes back to a .docx file.

Serializes modified XML parts and repacks into a DOCX archive.

Args: output_path: Path for the output file. If empty, overwrites the original.