hwp-mcp

Un servidor que permite a las IAs compatibles con MCP, como Claude, Cursor o ChatGPT, leer, modificar y crear nuevos documentos de Hangul (.hwp / .hwpx).

hwp-mcp es un servidor MCP (Model Context Protocol) que permite a los agentes de IA manejar directamente documentos de Hancom Office. No solo permite la lectura, sino también la modificación de texto, el relleno de plantillas y la creación de nuevos documentos.

¿Qué es este proyecto?

Este proyecto se divide en dos partes:

• 🔧 Lo que hizo rhwp (motor principal) — rhwp de Edward Kim es un motor de código abierto implementado en Rust + WebAssembly que ha descifrado mediante ingeniería inversa los formatos cerrados de Hangul (HWP 5.0 binario, HWPX/OWPML). El análisis, la extracción de tablas, imágenes, fórmulas y encabezados, la renderización SVG y la API de campos compatibles con Hancom: todas estas capacidades principales son proporcionadas por rhwp. Sin rhwp, este proyecto no existiría.

• 🤝 Lo que hizo hwp-mcp (adaptador de agente) — Una capa de servidor MCP ligera construida sobre @rhwp/core. Lo que hemos añadido es:

  • Firmas de herramientas amigables para agentes como read_hwp, fill_hwp_template, replace_hwp_text, para que los LLM como Claude/Cursor puedan invocarlas en lenguaje natural.

  • Un recorredor (traversal walker) centrado en escenarios que vuelca el cuerpo, tablas, imágenes, encabezados, pies de página, notas al pie y fórmulas de una sola vez.

  • Una capa de facilidad de uso para el manejo automático de combinación de celdas de tablas, consolidación automática de notas al pie/fórmulas.

  • Una capa de mutación a nivel de ZIP de .hwpx para eludir las limitaciones de round-trip de exportHwpx de rhwp 0.7.7 (la clave para hacer posible la escritura real).

  • Paquete npm hwp-mcp (instalación en una línea) + bootstrap de Node.js WASM.

Resumen: Un adaptador que permite a la IA leer y escribir documentos de Hangul de verdad. Por favor, envíe su agradecimiento por todas las capacidades de Hangul de código abierto al proyecto rhwp 🙏

Related MCP server: HWP-MCP

Instalación

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

Requiere Node.js 20 o superior.

Lista de herramientas

Estas son las 34 herramientas MCP expuestas por hwp-mcp v0.2. La lectura/renderizado es compatible con .hwp/.hwpx, la escritura es exclusiva para .hwpx.

Lectura (5)

Meta / Consulta (5)

Renderizado visual (4)

Escritura — Texto (5)

Escritura — Estructura (9)

Escritura — Formato (2)

Escritura — Imágenes / Tablas / Nuevo (4)

Matriz de extracción de contenido

Matriz de escritura

La escritura binaria de .hwp no es compatible en v0.2 debido a las limitaciones de round-trip de exportHwp de rhwp 0.7.7. Por favor, guarde como .hwpx en Hancom Office antes de usar las herramientas de escritura, o espere al lanzamiento de v0.3.

Ejemplos de uso

Leer documentos gubernamentales de Hangul

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

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

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

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

Rellenar plantillas

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

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

Reemplazo de texto

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

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

Crear un nuevo .hwpx

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

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

Extracción de imágenes

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

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

Renderizar página a SVG (para análisis visual)

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

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

O guardar en disco:

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

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

Limitaciones

Limitaciones conocidas de hwp-mcp v0.2:

• Escritura de .hwp no soportada — La lectura funciona tanto para .hwp como para .hwpx. La escritura es solo para .hwpx. Si se llama a una herramienta de escritura para una entrada .hwp, devolverá un mensaje de error claro. Por favor, guarde como .hwpx en Hancom Office antes de usar, o espere al lanzamiento de v0.3.

• Rechazo de guardado entre formatos — La entrada .hwpx solo se guarda como .hwpx.

• Extracción de encabezados/pies de página/notas al pie posible, cuadros de texto/notas al final/fórmulas en v0.3 — En el resultado de read_hwp_text, los encabezados se marcan como --- headers ---, los pies de página como --- footers --- y las notas al pie como bloques --- footnotes ---. La extracción de cuerpo de cuadros de texto, notas al final y fórmulas está prevista para v0.3.

• No hay coincidencia si el término de búsqueda abarca dos nodos de texto — Ej: Si un <hp:t> termina en "indus" y el siguiente comienza en "trial", "industrial" no coincidirá. Es la misma limitación que hwpctl de Hancom.

• Las tablas de create_hwpx_document se aplanan a filas de texto en v0.2 — Las tablas OWPML reales estarán en v0.3.

¿Cómo funciona?

• Lectura: @rhwp/core (el analizador Rust+WASM de rhwp) recorre secciones, párrafos, tablas (incluyendo celdas combinadas) e imágenes.

• Escritura (.hwpx): Analiza directamente Contents/section*.xml dentro del archivo ZIP, busca/reemplaza el nodo de texto <hp:t> y luego vuelve a empaquetar (el mimetype se almacena según la especificación). Es una capa para eludir el problema de round-trip de exportHwpx() de rhwp.

• Nuevo documento: Se crea con createBlankDocument + insertText de rhwp y luego se guarda con exportHwpx (el round-trip de texto es estable).

Créditos

rhwp (@edwardkim) — Analizador principal, renderizador, API de campos. Todo el trabajo de abrir el formato cerrado de Hangul es la base de este proyecto. Si puede, por favor apoye también ese proyecto: https://github.com/edwardkim/rhwp

hwp-mcp — Un adaptador MCP ligero sobre rhwp que permite a los agentes de IA invocarlo en lenguaje natural. Todas las capacidades principales son de rhwp, nosotros somos el cableado que lo conecta al LLM.

Cobertura

Grandes elementos restantes para v0.3: escritura binaria de .hwp, gráficos, definición/aplicación de estilos, extracción de cuerpo de cuadros de texto, 30 acciones de hwpctl (excluidas intencionalmente).

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.