DocuHand 🖐️

Give your AI agent hands to operate real Word & WPS documents on Windows.

DocuHand is a Model Context Protocol (MCP) server that lets AI agents (Claude Desktop, Hermes, Cursor, any MCP client) actually drive Microsoft Word and WPS Office via COM — not just read docx XML, but automate the real applications: legacy .doc binaries, documents currently open on screen, and print-fidelity PDF export through the word processor's own layout engine.

Works on both Microsoft Word and WPS Office — when Word is absent or crashes mid-batch, the WPS engine takes over transparently. (WPS support is believed to be unique among Office MCP servers.)

uvx docuhand serve

Security posture: zero network code (audited — see THREAT-MODEL.md): no telemetry, no update checks, a local JSONL audit log, and an explicit non-goals section.

Why DocuHand exists

Most Office MCP servers are built on python-docx — they manipulate XML in idealized files. Real-world documents are not idealized:

• 20-year-old .doc binaries that XML libraries cannot touch

• Files currently open and locked in Word/WPS right now

• WPS Office — the default suite for hundreds of millions of users

• CJK fonts that silently reset when text is replaced (the NameFarEast trap)

• Password-protected and corrupt files that pop modal dialogs and hang headless servers

DocuHand drives the real applications, hardened by a year of production use in government document processing. Every pitfall in docs/pitfalls.md cost real debugging time — you get them pre-solved.

Related MCP server: docx-mcp-server

Tools

Every tool returns structured JSON. Every error carries {error_code, human_message, llm_hint} — errors are data the agent reads to self-correct, not tracebacks it drowns in.

Quick start

Install from PyPI:

# with pip
pip install docuhand

# or with uv (also gives you the `uvx docuhand serve` one-liner)
uv tool install docuhand

Requirements: Windows with either Microsoft Word or WPS Office installed (either one is enough — the engine probes Word.Application first, then KWPS.Application, overridable with DOCUHAND_ENGINE=wps|word).

Add to your MCP client (Claude Desktop example):

{
  "mcpServers": {
    "docuhand": {
      "command": "docuhand",
      "args": ["serve"]
    }
  }
}

Then ask your agent: "Convert every .doc in D:\Reports to PDF" — see Examples.

Examples

Examples of what to ask your agent

Batch conversion — one call converts the whole folder:

"Convert every .doc file in D:\Reports to .docx"

Template fill with CJK font safety — layout and East-Asian fonts survive:

"Fill D:\Templates\notice.docx with name=Zhang San, amount=426, save it to my desktop"

Edit a document that's open on screen — the agent works in the user's live Word/WPS window:

"In the contract I have open right now, replace every 2023 with 2024 — don't save yet"

Mail-merge batch:

"Generate one offer letter per row in data.json from the offer.docx template"

A synthetic demo document lives in examples/demo-files/ (generated by scripts/make_demo_docs.py, no real/personal data), and examples/ has MCP client config snippets.

Security model (read before granting file access)

• 100% local execution — your documents never leave your machine

• No telemetry, ever

• Explicit path allowlist — set DOCUHAND_ALLOWLIST to a os.pathsep-separated list of directories; when unset, the fact that you launched the server yourself is the consent

• Read-only mode — set DOCUHAND_READONLY=1 to block every mutating tool; only inspect_document / extract_content / export_pdf remain

• JSONL audit log — every operation is appended to %LOCALAPPDATA%\docuhand\audit.jsonl (disable: DOCUHAND_AUDIT=off, relocate: DOCUHAND_AUDIT_PATH)

• Pre-COM container gates — broken/encrypted files are rejected in pure Python before the engine opens them, so a corrupt file can never pop a modal dialog on your desktop or hang the server (the #1 killer of headless Office automation)

Environment variables (DOCUHAND_ENGINE, DOCUHAND_ALLOWLIST, DOCUHAND_READONLY, DOCUHAND_AUDIT*, DOCUHAND_COM_TIMEOUT) must be declared in your MCP client's server config — hosts pass stdio servers a filtered environment.

Why not just use Copilot in Word / WPS AI?

Those are copilots — they serve the person sitting in front of the document, through a closed, human-driven interface with no public API. DocuHand is ground crew: it serves agents working unattended — batch jobs at 3 AM, pipelines, any MCP client. Different buyer, different mode of operation.

"Why operate legacy .doc files at all?" Nobody chooses legacy formats. Archives of millions of .doc files in government, healthcare, legal and banking systems are locked by compliance (retain-original requirements), ecosystem inertia (counterparties still sending .doc), and sheer scale. Converting them is one of our tools. Copilot can't touch them; python-docx can't either. Manual clerical work or DocuHand — those are the options.

DocuHand vs. XML-level Office tools

Architecture notes

The short version of the six decisions that make this survive real machines (full rationale in docs/pitfalls.md):

• One dedicated STA thread owns all COM — the asyncio event loop must never touch COM directly (RPC_E_WRONG_THREAD), and one serial queue means no WINWORD.EXE instance explosion. A stuck call times out and the thread is abandoned wholesale.

• Word → WPS failover — an engine that dies mid-call is discarded and the next one takes over; probe order is configurable.

• Errors are structured data for the calling agent, not stack traces.

• Safety is registration-time middleware, not "remember to check".

Roadmap

• v0.2: track_changes, compare_documents, protect/unprotect, Excel family

• Pro (separate, later): batch queue/concurrency, service mode, priority support

The free core stays free (MIT).

Development

git clone <this repo> && cd docuhand
uv sync

# CI-safe unit tests (no Office needed)
uv run pytest tests/unit

# COM integration tests (local machine with Word/WPS only, never CI)
uv run pytest tests -m com

License

MIT — free core, forever. Pro is a separate commercial license, later.