hwp-mcp

MCP server for reading and writing HWP/HWPX (Korean Hangul word processor) files.

Works with Claude Code, Claude Desktop, VS Code Copilot, Cursor, ChatGPT, and any MCP-compatible client.

Install

# Claude Code
claude mcp add hwp-mcp -- uvx --from hwp-mcp hwp-mcp

# Claude Desktop / Other clients (settings JSON)
{
  "mcpServers": {
    "hwp-mcp": {
      "command": "uvx",
      "args": ["--from", "hwp-mcp", "hwp-mcp"]
    }
  }
}

Tools

Read

Tool	Description
read_hwp	Read full document (text + tables + images)
read_hwp_text	Extract text only
read_hwp_tables	Extract tables as markdown
list_hwp_images	List embedded images
extract_hwp_images	Save images to disk

Write

Tool	Description
fill_hwp_template	Fill template placeholders (e.g. {{name}} -> John)
replace_hwp_text	Find and replace text
create_hwpx_document	Create new HWPX document with text and tables

Usage Examples

Read an HWP file

You: Read /path/to/document.hwp

AI: # document.hwp
    Format: .HWP | Paragraphs: 23 | Tables: 2 | Images: 1

    | Name | Position | Company |
    | --- | --- | --- |
    | Kim | CTO | Acme |
    ...

Fill a template

You: Fill template /path/to/form.hwp with name=Kim, company=Acme

AI: Saved: form_filled.hwp
    Total 2 replacements
      '{{name}}' -> 1
      '{{company}}' -> 1

Replace text in HWP

You: Replace "홍길동" with "남대현" in /path/to/document.hwp

AI: '홍길동' -> '남대현': 3 replacements
    Saved: document_modified.hwp

Create a new HWPX document

You: Create a document with title "Employee Info" and a table with columns Name, Role

AI: HWPX document created: employee.hwpx

Extract images

You: Extract images from /path/to/document.hwp

AI: Extracted 3 images to /path/to/document_images/
      - BIN0001.png
      - BIN0002.jpg
      - BIN0003.emf

Supported Formats

Format	Read	Write
HWP (v5.0)	Text, tables, images	Text replacement
HWPX (OWPML)	Text, tables, images	Text replacement, create new

How It Works

• HWP: Parses OLE/CFB binary format, decompresses zlib streams, decodes HWPTAG records (text, tables, images)
• HWPX: Extracts ZIP archive, parses OWPML XML (section*.xml) for text/tables, reads BinData/ for images
• Write: Rebuilds OLE container with modified stream data (custom CFB writer for size-changed streams)

License

MIT