hwp-mcp

A server that allows MCP-compatible AIs like Claude, Cursor, and ChatGPT to read, modify, and create Hangul documents (.hwp / .hwpx).

hwp-mcp is a Model Context Protocol (MCP) server that enables AI agents to directly handle Hancom Office documents. It supports not only reading, but also text modification, template filling, and creating new documents.

What is this project?

This project is divided into two parts:

• 🔧 What rhwp did (Core Engine) — Edward Kim's rhwp is an open-source engine that reverse-engineered the closed Hangul formats (HWP 5.0 binary, HWPX/OWPML) and implemented them in Rust + WebAssembly. Parsing, extraction of tables, images, equations, and headers, SVG rendering, and Hancom-compatible Field API — all these core capabilities are provided by rhwp. Without rhwp, this project would not exist.

• 🤝 What hwp-mcp did (Agent Adapter) — A thin MCP server layer built on top of @rhwp/core. What we added:

  • Agent-friendly tool signatures like read_hwp, fill_hwp_template, and replace_hwp_text — allowing LLMs like Claude/Cursor to call them in natural language.

  • A scenario-focused traversal walker that dumps body text, tables, images, headers, footers, footnotes, and equations all at once.

  • Usability layers such as automatic table cell merging and automatic footnote/equation consolidation.

  • A .hwpx ZIP-level mutation layer to bypass the round-trip limitations of rhwp 0.7.7's exportHwpx (the key to enabling actual writing).

  • The npm hwp-mcp package (one-line installation) + Node.js WASM bootstrap.

Summary: An adapter that allows AI to truly read and write Hangul documents. Please send all gratitude for the open Hangul capabilities to the rhwp project 🙏

Related MCP server: HWP-MCP

Installation

Claude Code

claude mcp add hwp-mcp -- npx -y hwp-mcp

Claude Desktop / Cursor / VS Code (settings JSON)

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

Requires Node.js 20 or higher.

Tool List

These are the 34 MCP tools exposed by hwp-mcp v0.2. Reading/rendering supports both .hwp and .hwpx, while writing is exclusive to .hwpx.

Reading (5)

Meta / Query (5)

Visual Rendering (4)

Writing — Text (5)

Writing — Structure (9)

Writing — Formatting (2)

Writing — Images / Tables / New (4)

Content Extraction Matrix

Writing Matrix

.hwp binary writing is not supported in v0.2 due to the exportHwp round-trip limitations of rhwp 0.7.7. Please save as .hwpx in Hancom Office before using writing tools, or wait for the v0.3 release.

Usage Examples

Reading Government Hangul Documents

나: /Users/me/2026년_시행계획.hwpx 읽어줘

AI: # 2026년_시행계획.hwpx
    형식: .HWPX | 문단: 153개 | 표: 15개 | 이미지: 2개

    Ⅰ. 추진 배경
    □ (글로벌 현황) 전세계 AI 솔루션 시장 규모는 ...

    ### 표 9 (7행 x 4열)
    | 도메인 | 입력 데이터 | 학습 내용 | 산업AI 솔루션 적용 기능 예시 |
    | --- | --- | --- | --- |
    | 기계 | · 센서 데이터 로그 ... | ... | ... |

Filling Templates

나: /path/to/form.hwpx 에서 {{이름}}=남대현, {{회사}}=포텐랩 으로 채워줘

AI: 저장 완료 (saved): form_filled.hwpx
    총 2건 치환 (2 replacements)
      '{{이름}}' → 1건
      '{{회사}}' → 1건

Text Replacement

나: /path/to/doc.hwpx 의 "산업AI" 를 "산업-AI" 로 바꿔줘

AI: '산업AI' → '산업-AI': 18건 교체 (replaced 18)
    저장 (saved): doc_modified.hwpx

Creating a New .hwpx

나: employees.hwpx 에 "사원 명부" 와 "두 번째 줄" 두 줄을 가진 문서 만들어줘

AI: HWPX 문서 생성 완료 (created): employees.hwpx

Extracting Images

나: /path/to/document.hwpx 에서 이미지 빼줘

AI: 이미지 2개를 추출했습니다 (extracted 2 images):
    저장 위치: /path/to/document_images
      - image_001.bmp
      - image_002.bmp

Rendering Pages to SVG (for visual analysis)

나: /path/to/document.hwpx 의 첫 페이지를 SVG로 보여줘

AI: <svg xmlns="..." width="793" height="1122" viewBox="...">
    <defs>...</defs>
    ...
    </svg>

Or save to disk:

나: /path/to/document.hwpx 모든 페이지 SVG로 저장해줘

AI: 9/9 페이지 SVG 저장 (rendered 9/9 pages):
    저장 위치: /path/to/document_pages
      - page_001.svg
      - page_002.svg ...

Limitations

Known constraints of hwp-mcp v0.2:

• .hwp writing not supported — Reading works for both .hwp/.hwpx. Writing is .hwpx only. Calling writing tools on .hwp input will return a clear error message. Please save as .hwpx in Hancom Office or wait for v0.3.

• Cross-format saving denied — .hwpx input is saved only as .hwpx.

• Headers/Footers/Footnotes extractable; Textboxes/Endnotes/Equations in v0.3 — In read_hwp_text results, headers are marked as --- headers ---, footers as --- footers ---, and footnotes as --- footnotes --- blocks. Textbox body, endnotes, and equation extraction are planned for v0.3.

• No matching if search term spans two text nodes — e.g., if one <hp:t> ends in "Industry" and the next starts with "AI", "IndustryAI" will not match. This is the same limitation as Hancom's hwpctl.

• Tables in create_hwpx_document are flattened to text rows in v0.2 — Real OWPML tables will be in v0.3.

How does it work?

• Reading: @rhwp/core (rhwp's Rust+WASM parser) traverses sections, paragraphs, tables (including merged cells), and images.

• Writing (.hwpx): Directly parses Contents/section*.xml inside the ZIP archive, performs search/replace on <hp:t> text nodes, and re-packages (mimetype stored as per spec). This is a layer to bypass rhwp's exportHwpx() round-trip issues.

• New Documents: Created using rhwp's createBlankDocument + insertText, then saved via exportHwpx (text round-trip is stable).

Credits

rhwp (@edwardkim) — Core parser, renderer, and Field API. All the work that opened up the closed Hangul format is the foundation of this project. If possible, please support that project as well: https://github.com/edwardkim/rhwp

hwp-mcp — A thin MCP adapter built on top of rhwp that turns it into tools that AI agents can call in natural language. All core capabilities belong to rhwp; we are just the wiring that connects it to LLMs.

Coverage

Remaining major items for v0.3: .hwp binary writing, charts, style definitions/application, textbox body extraction, hwpctl 30 Actions (intentionally excluded).

English

hwp-mcp is an MCP server for reading and writing Korean Hangul (.hwp / .hwpx) documents from Claude / Cursor / ChatGPT and any MCP-compatible client. Read works for both formats; write currently supports .hwpx (find/replace, template fill, create new doc) — .hwp write is planned for v0.3. Built on top of rhwp (Rust + WebAssembly HWP engine by Edward Kim, MIT). Install: claude mcp add hwp-mcp -- npx -y hwp-mcp.

License

MIT.