docx-comments
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., "@docx-comments Read research.docx and show me all comments and track changes"
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.
docx-comments-mcp
An MCP server for Claude Desktop that provides comprehensive read/write access to Word documents, including comments, track changes, and reply threads — features that python-docx doesn't fully expose.
Features
Read documents: Extract text, comments (with reply threads), and track changes
Add comments: Anchor comments to specific text in the document
Reply to comments: Create threaded replies on existing comments
Track changes: Make edits with insertions and deletions tracked
Resolve comments: Mark comments as done
Accept/reject changes: Apply or undo tracked changes
Related MCP server: docx-mcp
Installation
# Clone the repository
git clone https://github.com/your-username/docx-comments-mcp.git
cd docx-comments-mcp
# Install with uv
uv syncUsage with Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"docx-comments": {
"command": "uv",
"args": ["--directory", "/path/to/docx-comments-mcp", "run", "docx-comments-mcp"]
}
}
}Available Tools
read_document
Read a Word document and extract content, comments, and track changes.
Parameters:
path(required): Path to the .docx fileinclude_text(default: true): Include full document textinclude_comments(default: true): Include comments with anchorsinclude_track_changes(default: true): Include insertions/deletions
Returns:
{
"metadata": {
"path": "/path/to/file.docx",
"author": "Original Author",
"created": "2025-01-15T10:30:00Z",
"modified": "2025-01-18T14:22:00Z",
"word_count": 4523
},
"paragraphs": [
{"index": 0, "text": "The paragraph content...", "style": "Heading 1"}
],
"comments": [
{
"id": 0,
"author": "Dr. Smith",
"date": "2025-01-16T09:15:00Z",
"text": "Consider citing Main & Hesse here",
"anchor_text": "disorganized attachment patterns",
"anchor_paragraph": 12,
"resolved": false,
"replies": [
{
"id": 1,
"parent_id": 0,
"author": "Josh",
"date": "2025-01-17T11:00:00Z",
"text": "Added citation — see revision"
}
]
}
],
"track_changes": [
{
"id": 5,
"type": "deletion",
"author": "Dr. Smith",
"date": "2025-01-16T09:20:00Z",
"text": "invariably",
"paragraph": 8
}
]
}create_comment
Add a comment anchored to specific text in a Word document.
Parameters:
path(required): Path to the .docx fileanchor_text(required): Text to anchor the comment to (must exist and be unique)comment_text(required): The comment contentauthor(default: "Claude"): Comment author nameoutput_path(optional): Save to new file; if omitted, creates timestamped backup and overwrites
Returns:
{
"success": true,
"comment_id": 3,
"anchored_to": "the exact text that was matched",
"paragraph": 15,
"output_path": "/path/to/output.docx"
}create_reply
Add a reply to an existing comment.
Parameters:
path(required): Path to the .docx fileparent_comment_id(required): ID of comment to reply toreply_text(required): The reply contentauthor(default: "Claude"): Reply author nameoutput_path(optional): Save to new file; if omitted, creates backup
create_track_change
Make an edit with track changes enabled (insertion, deletion, or replacement).
Parameters:
path(required): Path to the .docx filefind_text(required): Text to find and modifyreplace_with(required): Replacement text (empty string for deletion)author(default: "Claude"): Change author nameoutput_path(optional): Save to new file; if omitted, creates backup
mark_comment_resolved
Mark a comment as resolved/done.
Parameters:
path(required): Path to the .docx filecomment_id(required): ID of comment to resolveoutput_path(optional): Save to new file; if omitted, creates backup
accept_change
Accept a tracked change (apply permanently).
Parameters:
path(required): Path to the .docx filechange_id(required): ID of the track change to acceptoutput_path(optional): Save to new file; if omitted, creates backup
reject_change
Reject a tracked change (undo the change).
Parameters:
path(required): Path to the .docx filechange_id(required): ID of the track change to rejectoutput_path(optional): Save to new file; if omitted, creates backup
Safety Features
Automatic backups: When modifying a file without specifying
output_path, a timestamped backup is created (e.g.,document.backup_20250119_143022.docx)Atomic writes: Uses temporary files and atomic moves to prevent corruption
Unique anchor matching: Comments require unique anchor text to prevent ambiguity
Development
# Install dev dependencies
uv sync
uv pip install pytest pytest-asyncio
# Run tests
uv run pytest -v
# Run specific test file
uv run pytest tests/test_reader.py -vArchitecture
src/docx_comments_mcp/
├── __init__.py
├── server.py # MCP server with tool definitions
├── reader.py # Read operations (document, comments, track changes)
├── writer.py # Write operations (add comments, track changes)
└── xml_helpers.py # Low-level OOXML parsing utilitiesLicense
MIT
Available Tools
9 toolsaccept_changeA
Accept a tracked change (apply the change permanently).
For insertions: The inserted text becomes part of the document. For deletions: The deleted text is permanently removed.
Args: path: Path to the .docx file change_id: ID of the track change to accept output_path: Save to new file; if omitted, creates timestamped backup and overwrites original
Returns: Dictionary containing: - success: True if successful - change_id: ID of the accepted change - change_type: "insertion" or "deletion" - output_path: Path where the file was saved
Inputs: path (required), change_id (required), output_path. Returns: object
create_commentA
Add a comment anchored to specific text in a Word document.
Args: path: Path to the .docx file anchor_text: Text to anchor the comment to (must exist and be unique in document) comment_text: The comment content author: Comment author name (default: "Claude") output_path: Save to new file; if omitted, creates timestamped backup and overwrites original
Returns: Dictionary containing: - success: True if successful - comment_id: ID of the created comment - anchored_to: The text the comment is anchored to - paragraph: Index of the paragraph containing the anchor - output_path: Path where the file was saved
Errors: - If anchor text is not found: {"success": false, "error": "Anchor text not found in document"} - If anchor text appears multiple times: {"success": false, "error": "Anchor text appears N times; provide more context for unique match"}
Inputs: path (required), anchor_text (required), comment_text (required), author, +1 more. Returns: object
create_replyA
Add a reply to an existing comment in a Word document.
Args: path: Path to the .docx file parent_comment_id: ID of the comment to reply to reply_text: The reply content author: Reply author name (default: "Claude") output_path: Save to new file; if omitted, creates timestamped backup and overwrites original
Returns: Dictionary containing: - success: True if successful - reply_id: ID of the created reply - parent_comment_id: ID of the parent comment - output_path: Path where the file was saved
Inputs: path (required), reply_text (required), parent_comment_id (required), author, +1 more. Returns: object
create_track_changeA
Make an edit with track changes enabled (insertion, deletion, or replacement).
Args: path: Path to the .docx file find_text: Text to find and modify (must exist and be unique) replace_with: Replacement text (use empty string for deletion-only) author: Change author name (default: "Claude") output_path: Save to new file; if omitted, creates timestamped backup and overwrites original
Returns: Dictionary containing: - success: True if successful - change_type: "replacement", "deletion", or "insertion" - original_text: The text that was changed - new_text: The replacement text - paragraph: Index of the paragraph containing the change - output_path: Path where the file was saved
Inputs: path (required), find_text (required), replace_with (required), author, +1 more. Returns: object
get_paragraph_rangeA
Get a specific range of paragraphs from a Word document.
Use after search_document to get more context around matches, or to read a specific section without loading the full document.
Args: path: Path to the .docx file start_index: First paragraph index (0-based, inclusive) end_index: Last paragraph index (0-based, inclusive) include_annotations: Include comments/track changes in range (default: False)
Returns: Dictionary containing: - start_index: Actual start (may be clamped) - end_index: Actual end (may be clamped) - total_paragraphs: Total paragraphs in document - paragraphs: List with index, text, style - comments: Comments in range (if include_annotations=True) - track_changes: Track changes in range (if include_annotations=True)
Inputs: path (required), end_index (required), start_index (required), include_annotations. Returns: object
mark_comment_resolvedA
Mark a comment as resolved/done.
Args: path: Path to the .docx file comment_id: ID of the comment to resolve output_path: Save to new file; if omitted, creates timestamped backup and overwrites original
Returns: Dictionary containing: - success: True if successful - comment_id: ID of the resolved comment - output_path: Path where the file was saved
Inputs: path (required), comment_id (required), output_path. Returns: object
read_documentA
Read a Word document and extract content, comments, and track changes.
Args: path: Path to the .docx file include_text: Include full document text (default: True) include_comments: Include comments with anchors (default: True) include_track_changes: Include insertions/deletions (default: True)
Returns: Dictionary containing: - metadata: Document metadata (path, author, created, modified, word_count) - paragraphs: List of paragraphs with index, text, and style - comments: List of comments with id, author, date, text, anchor_text, anchor_paragraph, resolved (boolean), and replies - track_changes: List of track changes with id, type (insertion/deletion), author, date, text, paragraph
Inputs: path (required), include_text, include_comments, include_track_changes. Returns: object
reject_changeA
Reject a tracked change (undo the change).
For insertions: The inserted text is removed. For deletions: The deleted text is restored.
Args: path: Path to the .docx file change_id: ID of the track change to reject output_path: Save to new file; if omitted, creates timestamped backup and overwrites original
Returns: Dictionary containing: - success: True if successful - change_id: ID of the rejected change - change_type: "insertion" or "deletion" - output_path: Path where the file was saved
Inputs: path (required), change_id (required), output_path. Returns: object
search_documentA
Search for text in a Word document.
Use this to find specific content without loading the entire document. Returns matching paragraphs with surrounding context.
Args: path: Path to the .docx file query: Text to search for case_sensitive: Match case exactly (default: False) context_paragraphs: Paragraphs to include before/after each match (default: 1) max_results: Maximum matches to return (default: 20) include_annotations: Include comments/track changes on matched paragraphs (default: False)
Returns: Dictionary containing: - query: The search query - case_sensitive: Whether search was case-sensitive - total_matches: Total matches found - matches_returned: Number returned (may be limited) - matches: List with paragraph_index, paragraph_text, paragraph_style, match_start, match_end, context_before, context_after, and optionally comments and track_changes
Inputs: path (required), query (required), max_results, case_sensitive, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct operation: comment creation, reply, resolution, track changes, acceptance/rejection, and document reading/search. No overlap in purpose.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_comment, accept_change, search_document), making the set predictable.
With 9 tools, the count is within the ideal 3-15 range and well-scoped for the server's focus on .docx comments and track changes.
The tool set covers core CRUD for comments and track changes, but lacks a tool to delete comments entirely (only mark resolved) and to list all track changes independently, though read_document includes them.
Maintenance
Related MCP Connectors
Create Word .docx files from sections or markdown, fill templates, and read text from a .docx.
Convert DOCX documents to and from PDF, TXT, HTML, ODT, JPG and RTF.
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Automate enterprise-grade documents from templates, merge and 100+ conversions: PDF, Office, HTML.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables reading and analyzing Word documents with advanced features including table extraction, OCR image analysis, full-text search, and intelligent caching for optimized performance on large documents.7MIT
- AlicenseBqualityDmaintenanceEnables comprehensive management of Microsoft Word documents with 30+ tools for reading, writing, formatting, template merging, image extraction, equation extraction, and style application.241MIT
- AlicenseAqualityBmaintenanceEditing of existing Word (.docx) files with formatting preservation. Supports comments, footnotes, and document comparison.3047Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to create, read, and manipulate Microsoft Word documents with rich editing capabilities.MIT