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

MCP Servers