Hwp MCP

🚀 HWP MCP Server

The MCP (Model Context Protocol) server allows LLMs to read and modify binary HWP (Hangul) documents through the HWP COM API.

🚀 Quick Start

The MCP server enables seamless interaction between LLMs and HWP documents. Here's a high - level architecture overview:

LLM ↔ MCP Server (Python/FastMCP) ↔ PowerShell Bridge (JSON stdin/stdout) ↔ HWP COM API ↔ Hangul

The Python MCP server manages a long - running PowerShell subprocess that hosts HWP COM objects.

✨ Features

• Full - fledged HWP Manipulation: Offers a comprehensive set of tools for document management, reading, writing, formatting, and more.
• High Coverage: Achieves 100% coverage of the HWP COM API 199 HParameterSet.

📦 Installation

Prerequisites

• Windows: The HWP COM API is only available on Windows.
• Hancom Office Hangul: Must be installed to provide the HWP COM server.
• PowerShell 5.1+: Included with Windows.
• Python >= 3.11

Installation Command

uv pip install -e .

💻 Usage Examples

Run MCP Server

python -m hwp_mcp.server

Claude Desktop Config

{
  "mcpServers": {
    "hwp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hwp-mcp", "hwp-mcp"]
    }
  }
}

📚 Documentation

MCP Tools (140)

The MCP tools provide a vast array of functions to interact with HWP documents. Below are some of the main categories:

Document Management (5)

Read (5)

Write (5)

Formatting (3)

Table (3)

Advanced (5)

Cursor & Navigation (11)

Field (12)

Advanced Table (11)

Enhanced Formatting (5)

Page & Section (10)

Image & Equation (3)

Form Control (3)

Document Info (5)

Print & Export (3)

Utility (4)

Bookmark & Hyperlink (6)

Header/Footer & Caption (2)

Document Operations (8)

Compatibility & Settings (3)

Control & Object (4)

Style & Script (4)

System & Security (11)

HParameterSet Actions (10)

Project Structure

hwp-mcp/
├── src/hwp_mcp/
│   ├── __init__.py
│   ├── _core.py         # FastMCP instance & shared helpers
│   ├── server.py        # Entry point, imports all tool modules
│   ├── bridge.py        # PowerShell subprocess manager
│   ├── commands.py      # JSON command builders
│   └── tools/           # MCP tool definitions (140 tools)
│       ├── cursor.py
│       ├── doc_info.py
│       ├── document.py
│       ├── drawing.py
│       ├── field.py
│       ├── form.py
│       ├── formatting.py
│       ├── hparam.py
│       ├── hwpobject.py
│       ├── page_section.py
│       ├── print_export.py
│       ├── system.py
│       ├── table.py
│       ├── text.py
│       └── utility.py
├── scripts/
│   ├── hwp_bridge.ps1   # PowerShell COM bridge dispatcher
│   └── handlers/        # 12 handler modules
│       ├── document.ps1
│       ├── text.ps1
│       ├── table.ps1
│       ├── style_format.ps1
│       ├── action.ps1
│       ├── cursor_selection.ps1
│       ├── field.ps1
│       ├── draw_object.ps1
│       ├── form_control.ps1
│       ├── document_info.ps1
│       ├── print_export.ps1
│       ├── utility.ps1
│       └── hwpobject_methods.ps1
├── tests/
│   ├── test_bridge.py   # Bridge unit tests
│   ├── test_commands.py # Command builder unit tests
│   └── test_server.py   # Server tool unit tests
└── pyproject.toml

Development

uv pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/

Limitations

• Windows only: The HWP COM API requires Windows.
• Hangul required: Hancom Office Hangul must be installed.
• Binary HWP only: HWPX (XML - based) needs a separate server.

📄 License

MIT