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.

<!-- mcp-name: io.github.kosh-jelly/docx-comments -->

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

Installation

# Clone the repository
git clone https://github.com/your-username/docx-comments-mcp.git
cd docx-comments-mcp

# Install with uv
uv sync

Usage 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 file
• include_text (default: true): Include full document text
• include_comments (default: true): Include comments with anchors
• include_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 file
• anchor_text (required): Text to anchor the comment to (must exist and be unique)
• comment_text (required): The comment content
• author (default: "Claude"): Comment author name
• output_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 file
• parent_comment_id (required): ID of comment to reply to
• reply_text (required): The reply content
• author (default: "Claude"): Reply author name
• output_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 file
• find_text (required): Text to find and modify
• replace_with (required): Replacement text (empty string for deletion)
• author (default: "Claude"): Change author name
• output_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 file
• comment_id (required): ID of comment to resolve
• output_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 file
• change_id (required): ID of the track change to accept
• output_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 file
• change_id (required): ID of the track change to reject
• output_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 -v

Architecture

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 utilities

License

MIT