DocuHand
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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, Cursor, Hermes, OpenClaw, or any other 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 PDF export through the word processor's own layout
engine.
Who it is for: you are running a smaller model β on a harness, locally, or on a cheap API β against real files. It is smart enough to be useful and not smart enough to be left alone. DocuHand gives it a stable tool surface so it does not have to reason about how to touch a document.
Who it is not for: if you are on a frontier subscription and your agent already writes the code you need, you will not get your money's worth here.
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 serveSecurity 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.
Using this from an AI agent
If you are an AI agent: read examples/AGENT-QUICKSTART.md. It is written for you β preconditions, the MCP config to paste, the exact tool sequence to run, and what to do when a step fails.
If you are a human wiring this up: paste the following into your agent. It is the prompt that was rehearsed end to end before it was published here.
I have a legacy .doc file that contains a table. Please use the docuhand MCP server to:
inspect it first (
inspect_document) and tell me the real format, page count, table count, and whether it is locked or encryptedextract its tables and show me the JSON grid (
extract_content)convert it to .docx (
convert_documents)fill the
DemoBookmarkin the converted file with a one-line note (fill_template), saving to a new fileDo not modify the original file.
No test file yet? One command downloads a synthetic .doc with a real table
in it and prints the path for you:
# PowerShell
irm https://raw.githubusercontent.com/H-Mon/docuhand/main/examples/quickstart.ps1 | iex
# Git Bash / WSL
curl -s https://raw.githubusercontent.com/H-Mon/docuhand/main/examples/quickstart.sh | bashRelated MCP server: Office-MCP
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
.docbinaries that XML libraries cannot touchFiles currently open and locked in Word/WPS right now
WPS Office β Kingsoft reported 676 million WPS Office monthly active devices in June 2026, so the "default suite" problem is not a niche
CJK fonts that silently reset when text is replaced (the
NameFarEasttrap)Password-protected and corrupt files that pop modal dialogs and hang headless servers
DocuHand drives the real applications, hardened by hands-on debugging on real Chinese-Windows machines. Every pitfall in docs/pitfalls.md cost real debugging time, and you get them pre-solved.
Tools
Tool | What it does |
| Pre-flight health check: real format vs extension, lock state, page/word counts, corruption & password detection, bookmarks, field codes |
| Batch |
| Bookmarks / |
| PDF via the real layout engine, optional page range |
| Text / tables (as JSON grids) / heading outline from legacy |
| Edit a document the user has open right now β changes appear in their window |
| Mail-merge style batch generation: one template Γ N data rows |
Every tool returns structured JSON. A failure returns
{"ok": false, "error": {error_code, human_message, llm_hint, details}}:
errors are data the agent reads to self-correct, not tracebacks it drowns in.
llm_hint says how to fix the call β bad path, wrong argument, file outside
the allowlist.
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 docuhandRequirements: 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), and
Python 3.12 or newer (the package requires >=3.12; on older
interpreters pip reports from versions: none).
It runs with your own user privileges: no admin rights, no service install, no daemon. It does not run on Linux or macOS: it drives the real Office engine through COM.
Test coverage: the development machine has WPS Office only, no Microsoft Word. Every end-to-end verification in this repository ran on that machine; the Word-side code paths are the one thing not yet verified against real Word. If you run on Word and hit a difference, please open an issue, because that is exactly the gap worth closing.
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"
Everything above runs against files already in this repo β no setup, no downloads:
File | What it is |
Legacy OLE2 | |
The same content, modern format | |
16 mixed | |
MCP client config snippet | |
The step-by-step guide written for AI agents | |
One-command demo fetch for PowerShell / bash |
All sample documents are synthetic (generated by
scripts/make_demo_docs.py) and contain no real or personal data.
Security model (read before granting file access)
100% local execution β your documents never leave your machine
No telemetry, ever
Explicit path allowlist β set
DOCUHAND_ALLOWLISTto aos.pathsep-separated list of directories; when unset, the fact that you launched the server yourself is the consentRead-only mode β set
DOCUHAND_READONLY=1to block every mutating tool; onlyinspect_document/extract_content/export_pdfremainJSONL 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, from batch jobs at 3 AM to pipelines, on 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 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
python-docx based | DocuHand | |
Legacy | β | β (real app required) |
Open/locked files | β | β
|
WPS Office | β | β dedicated engine |
CJK font safety | β οΈ n/a or silent corruption | β
hardened ( |
PDF fidelity | β οΈ re-layout | β print-engine export |
Corrupt/password files | β οΈ crash or hang | β pre-COM gates, structured errors |
Architecture notes
The short version of the four 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 familyPro (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 comPublication gates
This repository is public, so a mistake in a commit is a mistake anyone can find - and in the history, which is where it stays. Two hooks check for that before it leaves the machine:
bash scripts/install_precommit_hook.shpre-commit scans the staged diff and refuses a commit that would publish a real identity, a machine-specific path, a client detail, or a regional package mirror.
pre-push re-scans every tracked file before anything reaches a public remote, because a commit is local and reversible while a push is not.
The rules are in scripts/precommit_gate.py; scripts/publish_gate.py
does the same job for outward-facing text, where there is no commit to
hook into. Both allow technical wording on purpose - "Chinese-Windows",
"CJK", "East-Asian", NameFarEast describe the platform this tool
supports, not who uses it.
If a check is wrong, fix the rule rather than bypassing it:
git commit --no-verify works, but the gate prints what it would have
blocked.
License
MIT. Free core, forever. Pro is a separate commercial license, later.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
This server cannot be deployed
Maintenance
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Real Word and Excel for agents: open your .docx/.xlsm, read, propose, apply, get it back intact.
Document conversion and OCR for AI agents: PDF, Office docs, images to text.
Use your own Word templates to convert Markdown β DOCX/PDF/HTML from any MCP-compatible AI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to read, edit, and create Microsoft Word documents (.docx) with support for rich text, tables, and images, deployable locally or via SSE.3MIT
- FlicenseNot gradedqualityBmaintenanceAutomates Windows Office applications (WPS Office and Outlook) via COM automation, enabling AI assistants to perform spreadsheet, document, and email tasks.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to drive Microsoft Word for Windows via COM automation, including opening and creating documents, editing text, managing paragraphs, tables, images, styles, tracked changes, and exporting to PDF.3MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create and process office documents locally, including generating branded PDF, Word, Excel, and editable PowerPoint files from templates and themes, plus reading, OCR, form-filling, manipulation, and conversion of PDFs.1MIT