hwp-mcp

Ein Server, der es MCP-kompatiblen KIs wie Claude, Cursor oder ChatGPT ermöglicht, Hangul-Dokumente (.hwp / .hwpx) zu lesen, zu bearbeiten und neu zu erstellen.

hwp-mcp ist ein MCP-Server (Model Context Protocol), der es KI-Agenten ermöglicht, Hancom Office-Dokumente direkt zu verarbeiten. Neben dem Lesen sind auch Textbearbeitung, das Ausfüllen von Vorlagen und die Erstellung neuer Dokumente möglich.

Was ist das für ein Projekt?

Dieses Projekt besteht aus zwei Teilen:

• 🔧 Was rhwp geleistet hat (Kern-Engine) — Edward Kims rhwp ist eine Open-Source-Engine, die das geschlossene Hangul-Format (HWP 5.0 binary, HWPX/OWPML) durch Reverse Engineering entschlüsselt und in Rust + WebAssembly implementiert hat. Parsing, Extraktion von Tabellen, Bildern, Formeln und Kopfzeilen, SVG-Rendering sowie die Hancom-kompatible Field API — all diese Kernfähigkeiten werden von rhwp bereitgestellt. Ohne rhwp gäbe es dieses Projekt nicht.

• 🤝 Was hwp-mcp geleistet hat (Agenten-Adapter) — Eine schlanke MCP-Server-Schicht, die auf @rhwp/core aufbaut. Wir haben Folgendes hinzugefügt:

  • Agentenfreundliche Tool-Signaturen wie read_hwp, fill_hwp_template und replace_hwp_text, damit LLMs wie Claude/Cursor diese in natürlicher Sprache aufrufen können.

  • Einen szenariobasierten Traversal-Walker, der Text, Tabellen, Bilder, Kopf-/Fußzeilen, Fußnoten und Formeln auf einmal ausgibt.

  • Eine benutzerfreundliche Schicht für die automatische Verarbeitung von Tabellenzellenzusammenführungen und die Zusammenführung von Fußnoten/Formeln.

  • Eine .hwpx ZIP-Ebenen-Mutationsschicht, um die Einschränkungen des exportHwpx-Roundtrips von rhwp 0.7.7 zu umgehen (der Kern, der das Schreiben erst ermöglicht).

  • Das npm-Paket hwp-mcp (Installation mit einem Befehl) + Node.js WASM-Bootstrap.

Zusammenfassend: Ein Adapter, der es KIs ermöglicht, Hangul-Dokumente tatsächlich zu lesen und zu schreiben. Bitte richten Sie Ihren Dank für die Hangul-Fähigkeiten an das rhwp-Projekt 🙏

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"]
    }
  }
}

Node.js 20 oder höher erforderlich.

Tool-Liste

Dies sind die 34 MCP-Tools, die hwp-mcp v0.2 bereitstellt. Lesen/Rendern unterstützt sowohl .hwp als auch .hwpx, das Schreiben ist auf .hwpx beschränkt.

Lesen (5)

Meta / Abfrage (5)

Visuelles Rendering (4)

Schreiben — Text (5)

Schreiben — Struktur (9)

Schreiben — Formatierung (2)

Schreiben — Bilder / Tabellen / Neu (4)

Inhalts-Extraktionsmatrix

Schreibmatrix

Das Schreiben von .hwp-Binärdateien wird in v0.2 aufgrund der Einschränkungen des exportHwp-Roundtrips von rhwp 0.7.7 nicht unterstützt. Bitte speichern Sie die Datei in Hancom Office als .hwpx unter einem anderen Namen, bevor Sie die Schreib-Tools verwenden, oder warten Sie auf das Release v0.3.

Anwendungsbeispiele

Regierungs-Hangul-Dokument lesen

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

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

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

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

Vorlage ausfüllen

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

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

Textersatz

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

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

Neues .hwpx erstellen

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

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

Bilder extrahieren

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

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

Seite als SVG rendern (zur visuellen Analyse)

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

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

Oder auf Festplatte speichern:

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

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

Einschränkungen

Bekannte Einschränkungen von hwp-mcp v0.2:

• Kein Schreiben von .hwp — Lesen funktioniert für .hwp/.hwpx. Schreiben nur für .hwpx. Wenn Schreib-Tools für .hwp-Eingaben aufgerufen werden, wird eine klare Fehlermeldung zurückgegeben. Bitte als .hwpx speichern oder auf v0.3 warten.

• Kein Cross-Format-Speichern — .hwpx-Eingaben werden nur als .hwpx gespeichert.

• Kopf-/Fußzeilen/Fußnoten extrahierbar, Textboxen/Endnoten/Formeln in v0.3 — Im Ergebnis von read_hwp_text werden Kopfzeilen als --- headers ---, Fußzeilen als --- footers --- und Fußnoten als --- footnotes --- Blöcke angezeigt. Extraktion von Textboxen, Endnoten und Formeln ist für v0.3 geplant.

• Kein Matching, wenn Suchbegriff über zwei Textknoten verteilt ist — Beispiel: Wenn ein <hp:t> mit "Industrie" endet und das nächste mit "AI" beginnt, wird "IndustrieAI" nicht gefunden. Dies ist die gleiche Einschränkung wie bei Hancoms hwpctl.

• Tabellen in create_hwpx_document sind in v0.2 als Textzeilen abgeflacht — Echte OWPML-Tabellen kommen in v0.3.

Wie funktioniert es?

• Lesen: @rhwp/core (rhwps Rust+WASM-Parser) durchläuft Abschnitte, Absätze, Tabellen (inkl. verbundener Zellen) und Bilder.

• Schreiben (.hwpx): Die Contents/section*.xml innerhalb des ZIP-Archivs wird direkt geparst, die <hp:t>-Textknoten werden gesucht/ersetzt und dann neu verpackt (Mimetype gemäß Spezifikation gespeichert). Dies ist eine Schicht, um die exportHwpx()-Roundtrip-Probleme von rhwp zu umgehen.

• Neues Dokument: Erstellt mit rhwps createBlankDocument + insertText und dann mit exportHwpx gespeichert (Text-Roundtrip ist stabil).

Credits

rhwp (@edwardkim) — Kern-Parser, Renderer, Field API. Die gesamte Arbeit, das geschlossene Hangul-Format zu öffnen, ist das Fundament dieses Projekts. Wenn möglich, unterstützen Sie bitte auch dieses Projekt: https://github.com/edwardkim/rhwp

hwp-mcp — Ein schlanker MCP-Adapter, der rhwp in Werkzeuge umwandelt, die von KI-Agenten in natürlicher Sprache aufgerufen werden können. Alle Kernfähigkeiten stammen von rhwp; wir sind lediglich die Verkabelung, die sie mit dem LLM verbindet.

Abdeckung

Verbleibende große Punkte für v0.3: .hwp-Binärschreiben, Diagramme, Stil-Definitionen/-Anwendung, Textbox-Inhaltsextraktion, hwpctl 30 Actions (absichtlich ausgeschlossen).

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.