Features

| Category | Count | Description | | ------------------------ | ------ | ----------------------------------------------------------------------- | | Document Management | 7 | Create, open, save, save-as, copy, close, reload | | Content Addition | 8 | Paragraphs, headings, tables, lists, images, page breaks, sections, TOC | | Content Editing | 9 | Search, replace, preview, section replace, keyword edit, delete | | Table Operations | 8 | Rows, columns, merge/split cells, borders, shading | | Formatting | 20 | Page layout, paragraph, text, styles, hyperlinks | | Style Management | 3 | Create, modify, list styles | | Annotations & References | 8 | Bookmarks, comments, footnotes, endnotes, queries | | Total | 63 | |

Requirements

• Python >= 3.10
• uv package manager

Installation

# Clone the repository
git clone https://github.com/Zeke-777/SKILLful-mcp-docx-processor.git
cd SKILLful-mcp-docx-processor

# Install dependencies
uv sync

Configure MCP Server

Claude Code

For Claude Code CLI:

# Project-level (creates .mcp.json in current directory)
claude mcp add -s project docx-processor -- uv run --directory /path/to/SKILLful-mcp-docx-processor python server.py

# Or global (available in all projects)
claude mcp add -s user docx-processor -- uv run --directory /path/to/SKILLful-mcp-docx-processor python server.py

Replace /path/to/SKILLful-mcp-docx-processor with your actual project path.

Manual JSON Configuration

For other MCP clients, or to manually create .mcp.json / mcp_config.json:

{
  "mcpServers": {
    "docx-processor": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/SKILLful-mcp-docx-processor",
        "python",
        "server.py"
      ],
      "env": {}
    }
  }
}

Install Skill

Skill files support both project-level and global installation. Choose one as needed.

Project-level Installation

Takes effect for the current project only. Skill files reside within the project directory:

# Run in your target project's root directory
mkdir -p .claude/skills

# Copy Skill files to the target project
cp -r /path/to/SKILLful-mcp-docx-processor/skills/docx-process .claude/skills/

Global Installation

Takes effect for all projects. Skill files reside in the user's home directory:

# Copy Skill files to the global directory
mkdir -p ~/.claude/skills
cp -r /path/to/SKILLful-mcp-docx-processor/skills/docx-process ~/.claude/skills/

After installation, the directory structure is as follows:

.claude/              # Project-level  or  ~/.claude/  # Global
└── skills/
    └── docx-process/
        ├── SKILL.md                  # Route table
        └── references/
            ├── doc-management.md     # Document management
            ├── content-operations.md # Content operations
            ├── table-operations.md   # Table operations
            ├── formatting.md         # Formatting
            └── annotations-query.md  # Annotations & queries

Claude Code automatically loads SKILL.md before calling docx_process, ensuring every call has the complete route and parameter reference.

Usage

Once configured, the docx_process tool becomes available in Claude Code. The tool uses a single gateway pattern:

docx_process(route="create_document", params={"file_path": "output.docx"})
docx_process(route="add_heading", params={"text": "Hello World", "level": 1})
docx_process(route="save_document", params={})

The built-in docx-process skill automatically loads the route table and parameter specifications before each call, ensuring correct usage.

Architecture

server.py          -- MCP server with all handler logic (2,247 lines)
SKILL.md           -- Route table (loaded on every call)
references/*.md    -- 5 category reference docs (loaded on demand)

The server exposes one tool (docx_process) that dispatches to handler functions via a ROUTE_HANDLERS dictionary.

Context Efficiency

If all 63 routes were written into the tool's docstring or loaded at once, it would consume a large portion of the context window. This project uses on-demand Skill loading to significantly reduce context overhead:

| Loading Stage | Content | Lines | | ------------------ | -------------------------------- | ----------- | | Tool schema | Docstring (parameter specs only) | 6 | | Every call | SKILL.md route table | 116 | | On demand | Single reference file | 47-177 | | Total per call | | 169-299 |

Compared to a naive approach (docstring with full route list ~30 lines + full SKILL.md 595 lines = ~625 lines), context usage is reduced by 52-73%.

This means:

• More room for actual tasks — saved context can be used for document content and business logic
• Faster responses — fewer tokens means faster inference
• Lower costs — significantly fewer tokens consumed per call

Robustness

• File lock detection for all file operations
• Parameter validation across all routes (levels, rows/cols, colors, spacing, etc.)
• State management with overwrite warnings and cleanup on close
• Unified error handling with clear, actionable messages
• Save retry (3 attempts, 2s intervals) for locked files

Known Limitations

• Single-document model (opening a new document warns about closing the current one)
• No per-run rich text within a paragraph (whole-paragraph formatting only)
• No text box support
• No concurrent multi-user protection (designed for single-user MCP scenarios)

Acknowledgments

This project is built upon an extension of MCP-Doc, retaining its core DocxProcessor class architecture and 21 foundational document operations. It has been expanded to 63 routes with additional features including file lock detection and on-demand Skill loading. Thanks to the original author for the excellent work.

License

MIT