# hwp-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/treesoop/hwp-mcp  
**GitHub Stars:** 103  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hwp-mcp

## Description
MCP server for reading and writing HWP/HWPX (Korean Hangul) documents — built on rhwp. 34 tools, Claude/Cursor/ChatGPT compatible.

## Tools
Capabilities this server exposes over MCP:

- **read_hwp** — Read full HWP/HWPX document content as text + tables (markdown) + image listing. Args: file_path (absolute path).
- **read_hwp_text** — Extract plain body text from an HWP/HWPX file (no tables, no images). Args: file_path.
- **read_hwp_tables** — Extract every table from an HWP/HWPX file as GitHub-flavored markdown. Args: file_path.
- **convert_hwp_markdown** — Convert an HWP/HWPX document to Markdown preserving document flow order: tables as GFM in place, images extracted with relative links, equations inline ($…$), footnotes at end. If output_path is omitted, the Markdown string is returned inline with image placeholders. Args: file_path, output_path (optional .md path), image_dir (optional, default <md name>_images/ next to output).
- **list_hwp_images** — List embedded images (mime, byte length, locator) in an HWP/HWPX file. Args: file_path.
- **extract_hwp_images** — Save every embedded image to disk. Args: file_path, output_dir (optional; defaults to <file>_images/).
- **replace_hwp_text** — Find and replace text in an HWPX file. v0.2: only .hwpx is supported as input/output. Args: file_path, old_text, new_text, output_path (optional).
- **fill_hwp_template** — Fill multiple placeholders in an HWPX template. `replacements` is a JSON object string, e.g. {"{{name}}":"Kim","{{company}}":"Acme"}. v0.2: .hwpx only. Args: file_path, replacements, output_path (optional).
- **get_hwp_info** — Get document metadata (version, page count, section count, fonts used, totals for tables/images/footnotes/equations/headers/footers). Args: file_path.
- **get_hwp_page_def** — Get per-section page definition (paper size, margins, columns) and section properties. Useful for understanding document layout. Args: file_path.
- **get_hwp_field_value** — Get a Hancom field's current value by name. Args: file_path, name.
- **list_hwp_fields** — List Hancom-style fields (`<hp:fldBegin>`/end pairs) in the document, with name and type when available. Useful before fill_hwp_template. Args: file_path.
- **list_hwp_bindata** — List ZIP entries under BinData/ inside an .hwpx (image and binary attachments). Useful before replace_hwp_image. Args: file_path.
- **replace_hwp_image** — Replace an embedded image inside an .hwpx by overwriting its BinData/ ZIP entry with new file contents. `target` accepts either basename ('image1.bmp') or full entry path ('BinData/image1.bmp'). Args: file_path, target, source_path, output_path (optional).
- **render_hwp_page** — Render a single page of an HWP/HWPX document as SVG. If output_path is omitted, the raw SVG string is returned inline (useful for direct LLM consumption). Args: file_path, page (0-based, default 0), output_path (optional).
- **render_hwp_all_pages** — Render every page of an HWP/HWPX as SVG files in a directory. Args: file_path, output_dir (default <file>_pages/), max_pages (optional limit).
- **append_hwp_paragraph** — Append a new paragraph to the end of an .hwpx document body. Clones the last paragraph's structure (paraPr/charPr/style refs) and replaces text. Args: file_path, text, output_path (optional).
- **delete_hwp_paragraph** — Delete the Nth paragraph (0-based) from an .hwpx body. Args: file_path, index, output_path (optional).
- **append_hwp_table_row** — Append a new row to the Nth table (0-based) in an .hwpx. `cells` is a JSON string array of cell texts (length should match table column count). Args: file_path, table_index, cells, output_path (optional).
- **delete_hwp_table_row** — Delete the Mth row (0-based) from the Nth table (0-based) in an .hwpx. Args: file_path, table_index, row_index, output_path (optional).
- **set_hwp_paragraph_text** — Replace the entire text of the Nth paragraph (0-based) in an .hwpx body with new text. The paragraph attributes (paraPr/style refs) are preserved; runs are collapsed into a single <hp:run> with the new text. Args: file_path, index, text, output_path (optional).
- **set_hwp_cell_text** — Replace a single cell's text in a table inside an .hwpx. Args: file_path, table_index, row, col (all 0-based), text, output_path (optional).
- **set_hwp_field_value** — Set a Hancom field's value by name in an .hwpx (writes the new text between the matching `<hp:fldBegin name=...>` and `<hp:fldEnd>`). Use list_hwp_fields first to discover names. Args: file_path, name, value, output_path (optional).
- **append_hwp_table_column** — Append a new column to the Nth table in an .hwpx. `cells` is a JSON string array of cell texts (one per row, top-to-bottom). Args: file_path, table_index, cells, output_path (optional).
- **delete_hwp_table_column** — Delete the Mth column (0-based) from the Nth table in an .hwpx (removes one <hp:tc> from every row). Args: file_path, table_index, col_index, output_path (optional).
- **insert_hwp_image** — Insert a new image into an .hwpx — adds the file to BinData/, registers it in content.hpf, and appends a paragraph with an inline <hp:pic>. Args: file_path, source_path, ext (png/jpg/bmp/gif; auto from source_path if omitted), output_path (optional).
- **apply_hwp_paragraph_style** — Apply paragraph formatting (alignment·indent·line_spacing) to the Nth paragraph in an .hwpx. Adds a new paraPr to header.xml and retargets the paragraph's paraPrIDRef. align: LEFT|CENTER|RIGHT|JUSTIFY|DISTRIBUTE. Args: file_path, paragraph_index, align/indent/line_spacing (any subset), output_path (optional).
- **insert_hwp_table** — Insert a real OWPML table at the end of an .hwpx body (proper <hp:tbl>/<hp:tr>/<hp:tc>). headers and rows are both JSON string arrays — `headers` is a single-row array of strings, `rows` is an array of row arrays. Args: file_path, headers, rows, output_path (optional).
- **merge_hwp_cells_vertical** — Merge vertical cells across rows in a single column by setting rowSpan on the first cell and removing absorbed cells in following rows. Args: file_path, table_index, col, row_start, row_count (>=2), output_path (optional).
- **merge_hwp_cells_horizontal** — Merge horizontal cells in a row of a table by setting colSpan on the first cell and removing the absorbed cells. Args: file_path, table_index, row, col_start, col_count (>=2), output_path (optional).
- **apply_hwp_text_style** — Apply formatting (color/bold/italic/underline/font_size) to the first run that contains target_text. Adds a new charPr to header.xml and retargets the matching <hp:run>. Color is a 6-digit hex (e.g. 'FF0000'). Args: file_path, target_text, color/bold/italic/underline/font_size (any subset), output_path (optional).
- **delete_hwp_image** — Delete a BinData/ ZIP entry inside an .hwpx (effectively removes the embedded image bytes). Args: file_path, target (basename or full entry), output_path (optional).
- **render_hwp_html** — Render a single page of an HWP/HWPX as HTML. Useful for AI consumption when SVG isn't ideal. Args: file_path, page (0-based, default 0), output_path (optional).
- **render_hwp_equation_svg** — Render an OWPML equation script (e.g. 'TIMES LEFT ( {a} over {b} RIGHT )') to SVG. Args: script, font_size (HWP units, default 1300), color (default 0).
- **create_hwpx_document** — Create a new .hwpx file from a JSON content list of {type:'text',text} items. Tables (type:'table',headers,rows) are rendered as flat text rows in v0.2. Args: output_path (must end with .hwpx), content (JSON string of items).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What hwp-mcp does

hwp-mcp exposes Korean Hangul document operations through the Model Context Protocol. It can inspect `.hwp` and `.hwpx` files, extract structured content, render pages, and convert documents to Markdown. Reading covers body text, tables, embedded images, headers, footers, footnotes, and equations. Image extraction includes common embedded formats such as PNG, JPG, and BMP.

The server also supports HWPX editing and creation. Agents can replace text, populate `{{placeholder}}` fields, change paragraph or table-cell text, append or remove paragraphs and table rows or columns, merge cells, update images, apply text and paragraph styling, add images, and create a new text-based HWPX document.

## How it works

The package places an MCP adapter over `@rhwp/core`. rhwp handles HWP 5.0 binary and HWPX/OWPML parsing, while hwp-mcp provides workflows and tool signatures intended for natural-language agent use. Its traversal logic combines content from document sections into practical outputs, including Markdown tables and consolidated text for headers, footers, footnotes, and equations.

HWPX writes use ZIP-level document mutation in addition to the underlying engine. This allows changes to the XML and package entries needed for text, tables, images, and related document structures. Rendering tools can return a selected page or all pages as SVG, and an HTML rendering option is also available.

## Setup and configuration

Node.js 20 or newer is required. The server runs through `npx` and does not require Hancom Office, Python COM automation, or a Windows-only runtime. macOS, Windows, and Linux are supported, including Apple Silicon Macs.

For Claude Code, add it with:

```bash
claude mcp add hwp-mcp -- npx -y hwp-mcp@latest
```

For clients using an MCP settings file, configure the server with the `npx` command and `-y`, `hwp-mcp@latest` arguments:

```json
{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp@latest"]
    }
  }
}
```

Restart the client after changing its MCP configuration so the tools are loaded in a new session. The server communicates over standard input/output and requires no environment variables.

## Tools and capabilities

The tool set includes:

- Reading full documents, unified text, tables, metadata, page definitions, fields, and HWPX package entries.
- Converting documents to Markdown while preserving document order and representing tables as GitHub-Flavored Markdown.
- Listing or extracting embedded images and rendering pages as SVG or HTML.
- Replacing text, filling multiple placeholders, changing paragraph or cell content, and setting field values in HWPX files.
- Adding and removing paragraphs, table rows, and table columns; merging cells horizontally or vertically.
- Replacing, inserting, or deleting images and applying character or paragraph formatting.
- Creating a new HWPX document from text.

## Limitations and notes

Write operations are for HWPX; binary HWP files can be read and rendered but not edited by these tools. New HWPX table insertion is experimental, and its recognition by rhwp is incomplete. Text-box content, endnotes, charts, bookmarks, style definitions, and new headers or footers are outside the supported feature set described here. Equation SVG rendering is listed as a tool but is not associated with either HWP or HWPX in the support matrix.

_Full upstream README: https://allmcps.com/mcp/hwp-mcp/readme_