hwp-mcp

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

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

어떤 프로젝트인가요?

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

• 🔧 핵심 엔진: 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 무관하게 동작합니다.

설치 확인

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.2가 노출하는 34개 MCP 도구입니다. 읽기·렌더는 .hwp/.hwpx 모두 지원, 쓰기는 .hwpx 전용입니다.

읽기 (5)

도구	.hwp	.hwpx	설명
read_hwp	✅	✅	본문 + 표(마크다운) + 이미지 목록 한 번에
read_hwp_text	✅	✅	본문 + 머리말 + 꼬리말 + 각주 + 수식 통합 텍스트
read_hwp_tables	✅	✅	표를 GitHub 마크다운으로 (셀 병합 처리)
list_hwp_images	✅	✅	임베디드 이미지 목록 (mime, 바이트)
`extract_h

... View full README on GitHub