hwp-mcp

Claude · Cursor · ChatGPT 등 MCP 호환 AI에서 한글 문서(.hwp / .hwpx) 를 읽고 수정하고 새로 만들 수 있게 해주는 서버입니다.

hwp-mcp은 한컴오피스 문서를 AI 에이전트가 직접 다루도록 해주는 MCP(Model Context Protocol) 서버입니다. 읽기뿐 아니라 텍스트 수정, 템플릿 채우기, 새 문서 생성까지 가능합니다.

🍎 맥에서도 됩니다. 기존 HWP 자동화 도구 대부분은 한컴오피스 COM API 기반이라 Windows 전용이지만, hwp-mcp는 WebAssembly 엔진이라 macOS(Apple Silicon 포함) · Windows · Linux 어디서든 한컴오피스 설치 없이 동작합니다.

🏢 회사 전체가 같이 쓰려면: 같은 팀이 만든 Trina AX는 회사 서버에서 Claude Code를 돌리는 오픈소스 업무 공간입니다. 팀 폴더의 HWP/HWPX·PDF·Office 문서와 팀 스킬, MCP 서버를 직원 모두가 각자 폴더 권한 안에서 함께 씁니다.

어떤 프로젝트인가요?

이 프로젝트는 두 부분으로 나뉩니다.

• 🔧 핵심 엔진: 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

Claude Desktop / Cursor / VS Code (settings JSON)

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

Node.js 20 이상 필요. macOS · Windows · Linux 모두 지원 — 엔진이 WebAssembly 기반이라 한컴오피스 설치 없이 OS 무관하게 동작합니다. pywin32·COM 자동화처럼 Windows에 묶이지 않아 맥북에서도 위 한 줄로 끝입니다.

설치 확인

claude mcp list | grep hwp-mcp
# hwp-mcp: npx -y hwp-mcp  - ✓ Connected

✓ Connected 가 뜨면 끝.

처음 써보기 (60초)

설치 직후 동작 확인용 가장 짧은 검증:

나: 새 hwpx 문서 만들어줘. 파일 이름은 hello.hwpx 이고 "안녕 한글" 한 줄만 들어가게.
AI: HWPX 문서 생성 완료 (created): hello.hwpx

나: hello.hwpx 읽어줘.
AI: # hello.hwpx
    안녕 한글

위 두 단계가 되면 읽기·쓰기 양쪽 다 동작합니다. 이제 실제 문서로:

• ~/Downloads/공고문.hwp 읽어줘
• report.hwpx 의 {{이름}}을 남대현으로, {{날짜}}를 2026-05-26으로 채워줘
• document.hwpx 의 첫 페이지를 SVG로 보여줘

안 되면?

증상	원인 / 해결
✗ Failed to connect	v0.2.0 bin symlink 버그 — v0.2.1 이상으로 업그레이드 (아래)
설치는 됐는데 mcp__hwp-mcp__* 도구가 안 보임	Claude Code / Cursor 세션 재시작 필요 (MCP 도구는 세션 시작 시점에 로드됨)
npx: command not found 또는 ESM 에러	Node 20+ 인지 확인: node --version. Node 18 은 EOL — nvm install 20 또는 공식 설치
npx 가 옛 버전을 캐시	claude mcp add hwp-mcp -- npx -y hwp-mcp@latest (@latest 명시) 또는 npm cache clean --force
Claude Desktop / Cursor 에서 안 보임	설정 JSON 저장 후 앱 완전 종료 + 재실행 (백그라운드 트레이도 종료)

v0.2.0 → v0.2.1 업그레이드:

claude mcp remove hwp-mcp
claude mcp add hwp-mcp -- npx -y hwp-mcp@latest
claude mcp list | grep hwp-mcp   # ✓ Connected

설정 파일 방식(Claude Desktop/Cursor)이면 args 를 ["-y", "hwp-mcp@latest"] 로:

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

여전히 안 되면: Issues 에 node --version, claude mcp list 출력, 실행 OS 적어서 알려주세요.

---

도구 목록

hwp-mcp v0.3이 노출하는 35개 MCP 도구입니다. 읽기·렌더는 .hwp/.hwpx 모두 지원, 쓰기는 .hwpx 전용입니다.

읽기 / 변환 (6)

도구	.hwp	.hwpx	설명
read_hwp	✅	✅	본문 + 표(마크다운) + 이미지 목록 한 번에
read_hwp_text	✅	✅	본문 + 머리말 + 꼬리말 + 각주 + 수식 통합 텍스트
read_hwp_tables	✅	✅	표를 GitHub 마크다운으로 (셀 병합 처리)
convert_hwp_markdown	✅	✅	문서 → Markdown 변환 (문서 순서 유지, 표 GFM 제자리, 이미지 추출+상대링크, 수식 $…$, 각주 문서 끝)
list_hwp_images	✅	✅	임베디드 이미지 목록 (mime, 바이트)
extract_hwp_images	✅	✅	이미지를 디스크로 추출

메타 / 조회 (5)

도구	.hwp	.hwpx	설명
get_hwp_info	✅	✅	버전·페이지·글꼴·표/이미지/각주/수식 통계
get_hwp_page_def	✅	✅	섹션별 용지 크기·여백·단·헤더/푸터 마진
list_hwp_fields	✅	✅	한컴 필드 목록
get_hwp_field_value	✅	✅	필드 값 조회
list_hwp_bindata	–	✅	.hwpx BinData/ 엔트리 목록

시각 렌더 (4)

도구	.hwp	.hwpx	설명
render_hwp_page	✅	✅	특정 페이지 → SVG (인라인/파일)
render_hwp_all_pages	✅	✅	전체 페이지 SVG 일괄
render_hwp_html	✅	✅	페이지 → HTML
render_hwp_equation_svg	–	–	OWPML 수식 script → SVG

쓰기 — 텍스트 (5)

도구	.hwpx	설명
replace_hwp_text	✅	특정 문자열 찾아 바꾸기
fill_hwp_template	✅	{{이름}} 등 다중 자리표시자
set_hwp_paragraph_text	✅	N번째 문단 텍스트 통째 교체
set_hwp_cell_text	✅	표 셀 (행, 열) 텍스트 직접 설정
set_hwp_field_value	✅	필드 값 설정

쓰기 — 구조 (9)

도구	.hwpx	설명
append_hwp_paragraph	✅	본문 끝에 새 문단
delete_hwp_paragraph	✅	N번째 문단 삭제
append_hwp_table_row	✅	표 마지막에 새 행
delete_hwp_table_row	✅	표 행 삭제
append_hwp_table_column	✅	표 끝에 새 열 (모든 행에)
delete_hwp_table_column	✅	표 열 삭제
merge_hwp_cells_horizontal	✅	가로 셀 병합 (colSpan)
merge_hwp_cells_vertical	✅	세로 셀 병합 (rowSpan)
replace_hwp_image	✅	임베디드 이미지 교체

This is the beginning of the README. Read the rest at the original. Read the full README ↗