Hwp DocumentSAFE
MCP server for reading and writing HWP/HWPX (Korean Hangul) documents — built on rhwp. 34 tools, Claude/Cursor/ChatGPT compatible.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Claude · Cursor · ChatGPT 등 MCP 호환 AI에서 한글 문서(.hwp / .hwpx) 를 읽고 수정하고 새로 만들 수 있게 해주는 서버입니다.
[](https://www.npmjs.com/package/hwp-mcp) [](https://www.npmjs.com/package/hwp-mcp) [](https://github.com/edwardkim/rhwp) [](https://opensource.org/licenses/MIT) [](https://github.com/treesoop/hwp-mcp/releases/latest) [](#설치)
hwp-mcp은 한컴오피스 문서를 AI 에이전트가 직접 다루도록 해주는 MCP(Model Context Protocol) 서버입니다. 읽기뿐 아니라 텍스트 수정, 템플릿 채우기, 새 문서 생성까지 가능합니다.
🍎 맥에서도 됩니다. 기존 HWP 자동화 도구 대부분은 한컴오피스 COM API 기반이라 Windows 전용이지만, hwp-mcp는 WebAssembly 엔진이라 macOS(Apple Silicon 포함) · Windows · Linux 어디서든 한컴오피스 설치 없이 동작합니다.
어떤 프로젝트인가요?
이 프로젝트는 두 부분으로 나뉩니다.
- 🔧 핵심 엔진: rhwp — Edward Kim 님의 **rhwp**는 한글 포맷(HWP 5.0 binary, HWPX/OWPML)을 Rust + WebAssembly로 구현한 오픈소스 엔진입니다. 파싱, 표·이미지·수식·머리말 추출, SVG 렌더링, 한컴 호환 Field API 등 포맷 처리 능력을 제공합니다.
- 🤝 `hwp-mcp` 가 한 일 (에이전트 어댑터) —
@rhwp/core위에 얹은 MCP 서버 layer. 우리가 추가한 것은: read_hwp,fill_hwp_template,replace_hwp_text같은 에이전트 친화적 도구 시그니처 — Claude/Cursor 같은 LLM이 자연어로 호출할 수 있게- 본문·표·이미지·머리말·꼬리말·각주·수식을 한 번에 dump 하는 시나리오 중심 traversal walker
- 표 셀 병합 자동 처리, footnote/equation 자동 합본 같은 사용 편의 layer
- rhwp 0.7.7 의
exportHwpx라운드트립 한계를 우회하기 위한 `.hwpx` ZIP-level mutation layer (실제 쓰기를 가능하게 하는 핵심) - npm
hwp-mcp패키지 (한 줄 설치) + Node.js WASM 부트스트랩
요약: AI 에이전트가 한글 문서를 읽고 쓸 수 있게 해주는 어댑터입니다. 포맷 처리는 rhwp, 에이전트 연동은 hwp-mcp 가 담당합니다.
설치
Claude Code
claude mcp add hwp-mcp -- npx -y hwp-mcp
df994e675b26OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add hwp-mcp -- npx -y [email protected]
{
"mcpServers": {
"hwp-mcp": {
"command": "npx",
"args": [
"-y",
"[email protected]"
]
}
}
}Exposed tools (34)
19 read · 11 write · 4 destructive. Blast radius: 4 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
append_hwp_paragraph | read | Append a new paragraph to the end of an .hwpx document body. Clones the last paragraph |
append_hwp_table_column | read | Append a new column to the Nth table in an .hwpx. |
append_hwp_table_row | read | Append a new row to the Nth table (0-based) in an .hwpx. |
apply_hwp_paragraph_style | write | 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 |
apply_hwp_text_style | write | 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. |
create_hwpx_document | write | Create a new .hwpx file from a JSON content list of {type: |
delete_hwp_image | destructive | 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). |
delete_hwp_paragraph | destructive | Delete the Nth paragraph (0-based) from an .hwpx body. Args: file_path, index, output_path (optional). |
delete_hwp_table_column | destructive | 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). |
delete_hwp_table_row | destructive | 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). |
extract_hwp_images | write | Save every embedded image to disk. Args: file_path, output_dir (optional; defaults to <file>_images/). |
fill_hwp_template | read | Fill multiple placeholders in an HWPX template. |
get_hwp_field_value | read | Get a Hancom field |
get_hwp_info | read | 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 | read | Get per-section page definition (paper size, margins, columns) and section properties. Useful for understanding document layout. Args: file_path. |
insert_hwp_image | write | 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). |
insert_hwp_table | write | 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 — |
list_hwp_bindata | read | List ZIP entries under BinData/ inside an .hwpx (image and binary attachments). Useful before replace_hwp_image. Args: file_path. |
list_hwp_fields | read | List Hancom-style fields ( |
list_hwp_images | read | List embedded images (mime, byte length, locator) in an HWP/HWPX file. Args: file_path. |
merge_hwp_cells_horizontal | write | 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). |
merge_hwp_cells_vertical | write | 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). |
read_hwp | read | Read full HWP/HWPX document content as text + tables (markdown) + image listing. Args: file_path (absolute path). |
read_hwp_tables | read | Extract every table from an HWP/HWPX file as GitHub-flavored markdown. Args: file_path. |
read_hwp_text | read | Extract plain body text from an HWP/HWPX file (no tables, no images). Args: file_path. |
render_hwp_all_pages | read | 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). |
render_hwp_equation_svg | read | Render an OWPML equation script (e.g. |
render_hwp_html | read | Render a single page of an HWP/HWPX as HTML. Useful for AI consumption when SVG isn |
render_hwp_page | read | 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). |
replace_hwp_image | read | Replace an embedded image inside an .hwpx by overwriting its BinData/ ZIP entry with new file contents. |
replace_hwp_text | read | 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). |
set_hwp_cell_text | write | Replace a single cell |
set_hwp_field_value | write | Set a Hancom field |
set_hwp_paragraph_text | write | 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). |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (8)
delete_hwp_image, delete_hwp_paragraph, delete_hwp_table_column, delete_hwp_table_row
empty.hwp
simple.hwp
template.hwp
text_only.hwpx
with_equation.hwp
import { initRhwp } from "../../src/core/wasm-init.js";@modelcontextprotocol/sdk, jszip, @types/node, tsx, typescript, vitest
Gates applied: no_behavioural_pass.
df994e675b26full audit observations/trust-audit/mcp-server/treesoop__hwp-document.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | df994e675b26 | SAFE | B | 89 | first audit |
Questions
What is the Hwp Document MCP server?
MCP server for reading and writing HWP/HWPX (Korean Hangul) documents — built on rhwp. 34 tools, Claude/Cursor/ChatGPT compatible.
What tools does Hwp Document expose?
34 in total: 19 read-only, 11 that write, and 4 that can delete or overwrite (delete_hwp_image, delete_hwp_paragraph, delete_hwp_table_column, delete_hwp_table_row). Every one is listed on this page with its risk.
Is Hwp Document safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B. Separately from the audit: 4 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Hwp Document need?
No credential environment variables were found in its source, so it appears to need none.
How does Hwp Document run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as hwp-mcp at 0.3.0.
How current is this page?
The grade is for one exact copy of the source (df994e675b26), read on 2026-10-07. The repository is watched and re-audited when it changes.