hwpx

hwpx-mcp-server provides MCP-compliant access to Open XML-based HWPX documents using pure Python, without requiring the legacy HWP binary. It exposes a suite of tools for reading, searching, editing, and exporting HWPX content via MCP clients like Claude Desktop, Gemini CLI, VS Code (Copilot Chat), or editors configured with MCP settings. The server supports standard operations such as retrieving document metadata, extracting text, navigating structure, performing searches and replacements, and applying edits to paragraphs, headings, tables, and styles. Advanced mode (when enabled with HWPX_MCP_ADVANCED=1) unlocks additional tools for OPC parts, edit planning, and validation, enabling more complex workflows. To start, install the server with uvx or via pip and run the server binary, then configure MCP clients to point at the running uvx hwpx-mcp-server instance. The configuration examples show how to wire the server into common clients so you can send requests like get_document_info, get_document_text, find_text, add_paragraph, export_html, and more.

Prerequisites:

• Python >= 3.10
• Environment with internet access to install packages
• Optional: uv (for uvx) or pip to install the package

Installation steps (recommended):

1. Install via uvx (preferred MCP runner):

   • Run: uvx hwpx-mcp-server
   • This uses the hwpx-mcp-server package from PyPI

2. Or install via pip and run the server locally:

   • Install the package: pip install hwpx-mcp-server
   • Start the server: hwpx-mcp-server

3. Verify installation:

   • The server should start and listen on the default MCP transport (stdio) or as configured by your environment.

4. Optional: install Python dependencies for testing or extended features:

   • python -m pip install -e ".[test]" # if you want to run tests

Prerequisites recap: Python 3.10+, Python hwpx library (python-hwpx) as a dependency, and a MCP client configuration to connect to the running server.

Notes and tips:

• hwpx-mcp-server supports the Open XML .hwpx format (not the legacy .hwp binary). Ensure your documents are .hwpx when performing read/edit/export operations.
• You can enable advanced tools by setting HWPX_MCP_ADVANCED=1 in your environment or in the MCP config under env.
• The server is designed to be stateless per tool invocation; always provide a filename when invoking tools to ensure consistent behavior.
• Common environment variables:
  • HWPX_MCP_MAX_CHARS: default maximum characters returned by text-based tools (e.g., 10000)
  • HWPX_MCP_AUTOBACKUP: create a .bak before saving when enabled (1 to enable)
  • HWPX_MCP_ADVANCED: enable advanced toolset (1 to enable)
  • LOG_LEVEL: log verbosity (INFO, DEBUG, etc.)
• If you need to connect different MCP clients (Claude Desktop, Gemini CLI, VS Code, Cursor/Windsurf), reference the provided examples to configure their mcpServers settings to use command uvx with args ["hwpx-mcp-server"].
• For transport beyond stdio, you can run the server with the transport options (e.g., --transport streamable-http, --host, --port) as described in Transport Modes.