docx4j Word documents MCP server

docx4j-mcp

A Model Context Protocol server that exposes docx4j's engine to AI agents: read, convert and fill Word (.docx) documents from Claude Desktop, Claude Code, or any MCP client.

Engine: docx4j 17.1.0 (the server versions independently; the bundled docx4j version is in the pom, the server's startup log, and its MCP instructions).

Status: phase 3 — all tools work over stdio against released docx4j 17.0.4; packaged as a runnable jar, an .mcpb bundle, an OCI image and a Claude Code plugin. The plan, tool surface and phasing are in CR-mcp-server.md.

Build

Requires JDK 17+. All docx4j dependencies (docx4j 17.1.0, ImportXHTML 17.0.4) come from Maven Central.

mvn package            # -> target/docx4j-mcp.jar (shaded, runnable)
mvn test               # JUnit 5 tests against the tool handlers directly

Run

java -jar target/docx4j-mcp.jar --root /path/to/documents [--root ...] [--max-inline-chars N]

Bare directory arguments are also accepted as roots (this is what the .mcpb bundle's folder picker passes).

Claude Desktop, one click

Install docx4j-mcp.mcpb from the GitHub release (Settings → Extensions), pick the folders the server may touch, done. Built locally with packaging/build-mcpb.sh. Requires Java 17+ on your PATH.

Docker

docker run -i --rm -v /path/to/documents:/data ghcr.io/plutext/docx4j-mcp

(paths in tool calls are then container paths under /data; packaging/docker/Dockerfile to build locally).

Claude Code plugin

packaging/claude-plugin/ bundles the server config and a skill for the template/authoring workflows. Set DOCX4JMCPJAR (path to the jar) and optionally DOCX4JMCPROOTS.

Releasing

Tag vX.Y.Z: .github/workflows/release.yml builds jar + mcpb, attaches them to the GitHub release, pushes ghcr.io/plutext/docx4j-mcp, and publishes server.json (sha filled in) to the official MCP registry via GitHub OIDC.

Every file path an agent passes must resolve inside one of the --root directories (symlinks are resolved first). There is no default root; the server refuses to start without one. Logging goes to stderr; stdout is the protocol. Tools that return text inline cap it at --max-inline-chars (default 200000) and otherwise write to output_path or truncate with a marker.

Claude Code (.mcp.json in your project)

{
  "mcpServers": {
    "docx4j": {
      "command": "java",
      "args": ["-jar", "/path/to/docx4j-mcp.jar", "--root", "/path/to/documents"]
    }
  }
}

Claude Desktop (claudedesktopconfig.json)

{
  "mcpServers": {
    "docx4j": {
      "command": "java",
      "args": ["-jar", "/path/to/docx4j-mcp.jar", "--root", "/Users/you/Documents"]
    }
  }
}

Tools

Shortened. The full README is on GitHub.