hwp-mcp

Claude · Cursor · ChatGPTなどのMCP互換AIで、韓国語ワープロ文書（.hwp / .hwpx） を読み込み、修正し、新規作成できるようにするサーバーです。

hwp-mcpは、AIエージェントが直接Hancom Office文書を扱えるようにするMCP（Model Context Protocol）サーバーです。読み込みだけでなく、テキストの修正、テンプレートの入力、新規文書の作成まで可能です。

どのようなプロジェクトですか？

このプロジェクトは2つの部分に分かれています。

• 🔧 rhwpの役割（コアエンジン） — Edward Kim 氏の rhwp は、クローズドな韓国語フォーマット（HWP 5.0 binary, HWPX/OWPML）をすべてリバースエンジニアリングで解析し、Rust + WebAssemblyで実装したオープンソースエンジンです。パース、表・画像・数式・ヘッダーの抽出、SVGレンダリング、Hancom互換Field APIなど、すべての核心的な能力はrhwpが提供します。rhwpがなければ、このプロジェクトも存在しません。

• 🤝 hwp-mcpの役割（エージェントアダプター） — @rhwp/coreの上に構築された軽量なMCPサーバーレイヤーです。私たちが追加したのは以下の通りです：

  • read_hwp, fill_hwp_template, replace_hwp_text のようなエージェントフレンドリーなツールシグネチャ — Claude/CursorのようなLLMが自然言語で呼び出せるようにするため

  • 本文・表・画像・ヘッダー・フッター・脚注・数式を一度にダンプするシナリオ中心のトラバーサルウォーカー

  • 表のセル結合の自動処理、脚注/数式の自動統合といった使いやすさ向上のレイヤー

  • rhwp 0.7.7の exportHwpx ラウンドトリップの限界を回避するための**.hwpx ZIPレベルのミューテーションレイヤー**（実際の書き込みを可能にする核心）

  • npm hwp-mcp パッケージ（ワンラインインストール） + Node.js WASMブートストラップ

要約：AIが韓国語文書を実際に読み書きできるようにするアダプターです。すべてのオープンな韓国語処理能力に対する感謝は、rhwpプロジェクトにお送りください 🙏

Related MCP server: HWP-MCP

インストール

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以上が必要です。

ツール一覧

hwp-mcp v0.2が公開する34個のMCPツールです。読み込み・レンダリングは.hwp/.hwpxの両方をサポートし、書き込みは.hwpx専用です。

読み込み (5)

メタ / 照会 (5)

視覚レンダリング (4)

書き込み — テキスト (5)

書き込み — 構造 (9)

書き込み — 書式 (2)

書き込み — 画像 / 表 / 新規 (4)

コンテンツ抽出マトリックス

作成マトリックス

.hwp バイナリの書き込みは、rhwp 0.7.7の exportHwp ラウンドトリップの限界によりv0.2では未サポートです。Hancom Officeで .hwpx として名前を付けて保存してから書き込みツールを使用するか、v0.3のリリースをお待ちください。

使用例

政府の韓国語文書の読み込み

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

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

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

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

テンプレートの埋め込み

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

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

テキスト置換

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

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

新規 .hwpx の作成

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

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

画像抽出

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

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

ページをSVGとしてレンダリング（視覚分析用）

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

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

またはディスクに保存：

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

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

制限事項

hwp-mcp v0.2の既知の制約事項です。

• .hwp 書き込み未サポート — 読み込みは .hwp/.hwpx 両方可能です。書き込みは .hwpx のみです。.hwp 入力に対して書き込みツールを呼び出すと、明確なエラーメッセージを返します。Hancom Officeで .hwpx として名前を付けて保存してから使用するか、v0.3のリリースをお待ちください。

• クロスフォーマット保存の拒否 — .hwpx 入力は .hwpx としてのみ保存されます。

• ヘッダー/フッター/脚注は抽出可能、テキストボックス/文末脚注/数式はv0.3 — read_hwp_text の結果において、ヘッダーは --- headers ---、フッターは --- footers ---、脚注は --- footnotes --- ブロックとして表示されます。テキストボックス本文、文末脚注、数式の抽出はv0.3予定です。

• 検索語が2つのテキストノードにまたがる場合はマッチング不可 — 例：1つの <hp:t> が「産業」で終わり、次が「AI」で始まる場合、「産業AI」はマッチングしません。これはHancomのhwpctlと同じ制限です。

• create_hwpx_document の表はv0.2ではテキスト行としてフラット化 — 本格的なOWPML表はv0.3で対応予定です。

どのように動作しますか？

• 読み込み: @rhwp/core (rhwpのRust+WASMパーサー) がセクション・段落・表（結合セル含む）・画像をトラバースします。

• 書き込み (.hwpx): ZIPアーカイブ内の Contents/section*.xml を直接パースして <hp:t> テキストノードを検索/置換した後、再パッケージ化します（mimetypeは仕様通りstored）。rhwpの exportHwpx() ラウンドトリップ問題を回避するためのレイヤーです。

• 新規文書: rhwpの createBlankDocument + insertText で作成した後、exportHwpx で保存します（テキストのラウンドトリップが安定しているため）。

クレジット

rhwp (@edwardkim) — 核心的なパーサー・レンダラー・Field API。クローズドな韓国語フォーマットをオープンにしたすべての作業が、このプロジェクトの土台です。可能であれば、そのプロジェクトも応援してください: https://github.com/edwardkim/rhwp

hwp-mcp — rhwpの上にAIエージェントが自然言語で呼び出せるようにツール化した軽量なMCPアダプター。核心的な能力はすべてrhwpのものであり、私たちはそれをLLMに接続する配線（wiring）を行っています。

カバレッジ

残りのv0.3の大きな項目：.hwp バイナリ書き込み、チャート、スタイル定義・適用、テキストボックス本文抽出、hwpctl 30 Actions（意図的に除外）。

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.