Provides automated access to HWPX documents for viewing, searching, editing, and saving using MCP clients.
Configuration
View docs{
"mcpServers": {
"airmang-hwpx-mcp-server": {
"command": "uvx",
"args": [
"hwpx-mcp-server"
],
"env": {
"LOG_LEVEL": "INFO",
"HWPX_MCP_HARDENING": "0",
"HWPX_MCP_AUTOBACKUP": "1",
"HWPX_MCP_PAGING_PARA_LIMIT": "200"
}
}
}
}You can run an MCP server for HWPX documents that lets you open, search, edit, and save HWPX files directly without a Hangul word processor. Connect it to MCP clients like Gemini or Claude Desktop to automate document creation, editing, and exploration.
You will connect an MCP client to the local HWPX MCP server so you can open documents, navigate sections, edit text and objects, manage tables and styles, and save backups automatically. Start the server from your development workspace and use the clientβs MCP configuration to point to this server. Use the provided document locators to open local files or reference remote documents when you run operations. When the hardening editing pipeline is enabled, you gain additional safety checks and review steps for edits. Use search and context tools to locate content and extract surrounding text for review while preserving privacy.
Prerequisites: you should have Python installed and ready, and you will use a local MCP controller to start the server. You also need the uv package manager and its command-line interface to run the MCP server. The server runs in the current working directory by default, so you can start immediately after installation.
Step by step setup you can follow in your environment is as follows.
uvx hwpx-mcp-serverConfiguration at a glance shows how to define the MCP server for your client. You can add environment variables to tune paging, enable automatic backups, and control log verbosity. The server interpretation of document paths is based on the current working directory, so no extra directory configuration is required in most cases.
Security and hardening options offer two modes. By enabling the hardening flag, you activate a three-step edit workflow (Plan β Preview β Apply) and expanded tools for search and contextual review. When the flag is off or not set, you keep the original tool surface while still benefiting from the schema sanitization.
If you want to quickly verify all capabilities, you can exercise end-to-end tests that run the server tools, edit text, tables, and memo fields, read OPC package parts, and confirm backup creation.
The server integrates with a Python-based stack and uses the pure Python HwpxDocument API. You can run the test suite to validate core functionality before deploying to production.
Use the discriminated union document locator when issuing tool inputs. Local files can be targeted by path, while HTTP backends allow URIs when you run the server in HTTP storage mode. Pre-registered handles let you reference documents loaded by the hardening pipeline for subsequent search, context, and editing tasks.
If you encounter issues with large document dumps, adjust the paging limit via HWPX_MCP_PAGING_PARA_LIMIT or by specifying limit when you call read_text. For safety during edits, enable HWPX_MCP_AUTOBACKUP to create a .bak backup before saving changes. If you enable hardening, you can expect detailed plan, preview, and apply feedback, including potential ambiguous targets or unsafe operations that you must resolve before applying changes.
Retrieve document metadata and a summary of paragraphs and headers.
List document sections to understand structure.
List headers within the document.
Extract text with pagination and support for highlights and footnotes.
Fetch specific paragraphs by index for targeted review.
Search text with optional context radius for surrounding content.
Regex or keyword search across the document with stable node identifiers.
Retrieve surrounding context for a given paragraph or node.
Replace text while preserving styles; use dryRun for preview.
Append new paragraphs to the document.
Insert multiple paragraphs in a single operation.
Create a new table within the document.
Serialize the full table grid with cell ownership and spans.
Set text in a table cell with options for merging and auto-fit.
Replace a table region with new content.
Split a merged cell to reveal the original grid.
Insert graphical shapes into the document.
Insert controls or interactive elements.
Add a memo annotation to the document.
Attach a memo field to a specific location.
Add a memo attached to a specific anchor within the text.
Remove a memo annotation from the document.
Create a validated edit plan with a planId.
Preview an edit plan and review diffs, warnings, and safety scores.
Apply an approved edit plan to the document.
Ensure required run styles exist in the document.
List or create text styles and bullet lists.
Apply styles to specific text ranges.
Apply styles to entire paragraphs.
Save the current document.
Save the document under a new name.
Create a new blank document.
Find XML elements by tag name.
Find XML elements by attribute value.
Check the document structure for validity.
Lint text for style and conventions.
List all OPC parts inside the HWPX package (read-only).
Read a specific OPC part as text with encoding support.
Return a part's XML as a string.