HWP-MCP

You can run HWP-MCP as a Python-based Model Context Protocol server to allow AI models to create, edit, and manipulate Hangul Word Processor documents. This MCP server exposes functions for document generation, text editing, table operations, and batch tasks so you can drive HWP from an AI agent or automation workflow.

How to use

To connect an MCP client (such as Claude or other compatible AI tools) to the HWP-MCP server, register the MCP endpoint as a local stdio server. You start the server locally and then reference it from the client configuration so the AI can issue document-related commands.

How to install

Prerequisites: ensure you have Windows, a Hangul HWP-compatible environment, and Python 3.7 or later.

Step 1: Clone the repository and enter the project directory.

git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp

Step 2: Install dependencies listed in the requirements file.

pip install -r requirements.txt

Step 3: (Optional) Install the MCP package if you want the client tooling.

pip install mcp

Step 4: Run the MCP server locally using the Python script shown in the client example. Use your actual path to the script file.

python /path/to/hwp-mcp/hwp_mcp_stdio_server.py

Additional sections

Configuration example for client integration include a stdio server entry like the following. This registers a Python-based MCP server named with a short identifier and points to the server script that provides the HWP control functions.

{
  "mcpServers": {
    "hwp": {
      "command": "python",
      "args": ["경로/hwp-mcp/hwp_mcp_stdio_server.py"]
    }
  }
}

Key functions you can call include creating new documents, inserting text, creating and filling tables, saving documents, and batch executing multiple actions. The server exposes the following core operations: hwp_create, hwp_insert_text, hwp_insert_table, hwp_fill_table_with_data, hwp_fill_column_numbers, hwp_save, hwp_batch_operations, and hwp_set_font.

Important notes and troubleshooting:

• Ensure the Hangul program is running and accessible before connecting. If the program is not active, connections may fail.
• When working with tables, data entry will place values into the expected cells once the current cursor position is correctly set. If you encounter cursor-related issues, reinitialize the cursor position before filling data.
• If a security module is involved for file access prompts, follow the guidance for the Windows security prompts and proceed with the standard open/save flow after the module is registered.

Tools and capabilities

The MCP server provides a set of concrete functions to manipulate Hangul Word Processor documents. Each function handles a specific action, enabling an AI to orchestrate full document workflows.

Available tools

hwp_create

Create a new HWP document and initialize a working file in the HWP environment.

hwp_insert_text

Insert specified text into the currently focused position in the document.

hwp_insert_table

Create a new table with a given number of rows and columns at the current cursor location.

hwp_fill_table_with_data

Fill a specified table with the provided two-dimensional data array, with an option to treat the first row as a header.

hwp_fill_column_numbers

Populate a column with consecutive numbers, starting from a defined value and continuing to an end value.

hwp_save

Save the current document to a given path.

hwp_batch_operations

Execute multiple HWP actions in sequence as a single batch.

hwp_set_font

Apply font properties such as size and weight to the selected text or document region.