SKILLful MCP Docx Processor

English | 中文

A Word document processing service based on FastMCP and python-docx, exposing a single gateway tool (docx_process) that routes to 63 operations, covering the full document lifecycle: creation, editing, formatting, and querying.

Designed for seamless integration with Claude Code via the MCP protocol and Claude's skill system.

Features

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:

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