python-hwpx-automation MCP
An MCP server and CLI for Korean HWPX documents: text and table edits, form filling and plan-based document creation.
- 69 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Edit tools save changes to documents immediately; work is limited to the folders in `HWPX_AUTOMATION_WORKSPACE_ROOTS`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/python-hwpx-automationDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Edit tools save changes to documents immediately; work is limited to the folders in `HWPX_AUTOMATION_WORKSPACE_ROOTS`.
This is third-party code. Review the repository files before installing.
What it does
python-hwpx-automation is an application layer over the `python-hwpx` engine for HWPX, the document format of the Korean Hancom office suite. The package offers a Python API, the `hwpx` command and an optional MCP server, `hwpx-automation-mcp`. An agent reads document structure, searches and replaces text, edits tables, fills forms through an analyse, fill, verify flow, runs mail merge, creates a document from a declarative plan, builds previews and repairs damaged files. Hancom Office and Windows are not required. The model sends operations and never edits raw XML. Saving goes through a single integrity gate: if the check fails, nothing is written. Small local models get a `minimal` profile with six tools. The recommended order is a copy of the document first, then the smallest edit, then a re-read of the result.
Who it is for. People who prepare Korean official documents and forms in HWPX and hand filling and edits to an agent.
Good fit when
- A HWPX form must be filled from data and the result verified before sending.
- A mail merge of documents from a template with field substitution is needed.
- An agent replaces text in HWPX and the document formatting has to survive.
- A new document is built from a JSON plan with headings, paragraphs and tables.
Not a fit when
- Your main task involves DOCX or PDF: the server targets HWPX and reads other formats only through an extra package.
- You need a PDF with exact Hancom layout: rendering requires Hancom Office installed on the computer.
- Files sit outside the allowed folders: paths beyond `HWPX_AUTOMATION_WORKSPACE_ROOTS` are blocked.
Example request
Copy `report.hwpx`, put the values from `data.csv` into the table, re-read the result and show any mismatches.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
HWPX_AUTOMATION_WORKSPACE_ROOTSrequired- JSON array of folders where documents may be handled.
HWPX_AUTOMATION_PROFILE- The value `minimal` keeps six tools for small models.
HWPX_AUTOMATION_ADVANCED- The value `1` enables inspection and diagnostic tools.
Limitations
Needs Python 3.10 or newer and `python-hwpx` 6.5.0 or later. Edit tools save at once, so work on a copy of the document: a `.bak` backup is made before writing by default. GUI clients start the server from a system folder, so set the document folders in `HWPX_AUTOMATION_WORKSPACE_ROOTS` from the start. Reading PDF, DOCX and XLSX needs the extra `[ingest]` package. The README and most documentation are in Korean.
How to disable. Remove the `hwpx` block from the MCP client settings and, if needed, run `pip uninstall python-hwpx-automation`. `.bak` backups next to documents are deleted by hand.
FAQ
How do I connect the MCP server?
Install the package with the `[mcp]` extra and add an `hwpx` server to the client configuration with the `uvx` command and the arguments `--from`, `python-hwpx-automation[mcp]==7.3.1`, `hwpx-automation-mcp`. Configurations are given for Claude Desktop, VS Code, Gemini CLI, Cursor and Windsurf.
Is Hancom Office required?
No. Editing, form filling and document creation work without Hancom Office or Windows. It is needed only for PDF rendering with `hwpx render-pdf`.
What if a model gets lost among the tools?
Start the server with the `minimal` profile: `hwpx-automation-mcp --profile minimal`. Six tools remain, such as `read_outline`, `apply_text_changes` and `validate_document`.
How do I protect the original document?
Call `copy_document` first, edit the copy and re-read the result. A `.bak` backup is made before writing by default (`HWPX_AUTOMATION_AUTOBACKUP=1`).
Can I use it without MCP?
Yes. The base install gives a Python API and the `hwpx` command, and the MCP server is added by the `[mcp]` extra.
Discussion
No questions or reviews yet.
Related
MCP serversMCP server that reads, edits and creates Korean HWP and HWPX documents without Hancom Office on macOS, Windows and Linux.
A skill that creates and edits HWPX documents, converts HWP, and builds official letters and reports from a JSON spec
A skill that reads, creates and edits Korean hwp and hwpx documents from the agent, with no Hancom Office and no conversion
CLI and MCP server that turn Korean HWP and HWPX, PDF and Office files into Markdown and fill forms from templates
Adeu: an MCP server, skill and CLI for editing .docx through an agent with real Track Changes, comments and version diffs.
MCP Word server for docx editing with tracked changes: comments, footnotes, version comparison and a change log, all visible in Word
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| python-hwpx-automation (this card) | no | not required | 69 | |
| hwp-mcp | no | not required | 107 | reads, edits and creates HWP and HWPX; this one focuses on form filling, edit rollback, mail merge and a small-model profile |
| hwpx-skill | no | 308 | a skill with HWP conversion and letter assembly; this is a server with MCP tools and a CLI |
README in short
The package is one of three projects: the `python-hwpx` engine, this application layer and the `hwpx-plugins` bundle that helps an agent choose tools. The repository holds example skills for form filling, reference-preserving edits and template generation.