Skip to main content
Glama

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 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

Available Tools

9 tools
accept_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

    A4.3/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct operation: comment creation, reply, resolution, track changes, acceptance/rejection, and document reading/search. No overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_comment, accept_change, search_document), making the set predictable.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers