맥에서 한컴오피스 없이 한글 문서 읽고, 변환하고, 양식까지 채우는 법
지난 편에서는 Scrapling MCP로 Cloudflare 봇 검사를 통과하는 스크래퍼를 Claude Code에 붙였습니다. 이번 편에서는 한국에서 개발하다 보면 한 번쯤 막히는 파일, 한글(HWP) 문서를 다룹니다. hwp-mcp를 연결하면 맥에서도 한컴오피스 없이 AI가 한글 문서를 읽고, 마크다운으로 바꾸고, 양식의 빈칸까지 채울 수 있습니다.
왜 한글 MCP가 필요한가
Claude 채팅에 공식적으로 올릴 수 있는 문서는 PDF, DOCX, CSV, TXT, HTML, ODT, RTF, EPUB, JSON, XLSX입니다. HWP는 이 목록에 없습니다. 그런데 정부지원사업 공고문, 학교 안내문, 공모전 신청서는 여전히 .hwp로 배포되는 경우가 많습니다.
우회 방법이 없는 것은 아닙니다.
- PDF로 변환해서 올리기: 읽기는 되지만, 수정한 결과를 한글 파일로 돌려받을 수 없습니다.
- 코드 실행 환경에서 즉석 코드로 뜯어보기: Claude가 그때그때 코드를 짜서 해석하기 때문에 결과가 매번 다르고, 수정·저장할 때 파일이 깨질 위험이 큽니다.
MCP는 검증된 전용 도구를 서랍에 넣어두는 것과 같습니다. 즉석에서 공구를 만들어 쓰는 대신, 언제 꺼내도 같은 방식으로 동작하는 도구를 쓰는 것입니다. 한글 문서를 반복해서 다뤄야 한다면 이 차이가 결과의 안정성을 결정합니다.
HWP vs HWPX, 그리고 hwp-mcp의 구조
HWP vs HWPX
한글 문서에는 두 가지 형식이 있습니다.
- HWP(.hwp): 한컴의 예전 바이너리(binary) 포맷입니다. 바이너리는 사람이 읽을 수 있는 글자가 아니라 프로그램만 해석할 수 있는 데이터 덩어리로 저장된 형식으로, 전용 해석기(파서)가 있어야 열 수 있습니다. 밀봉된 통조림에 가깝습니다.
- HWPX(.hwpx): ZIP 압축파일 안에 XML 문서들이 들어 있는 구조로, 워드의 .docx와 같은 방식입니다. 지퍼백에 든 반찬처럼 한글 프로그램 없이도 열어서 내용만 바꾸고 다시 닫을 수 있습니다.
이 차이 때문에 hwp-mcp는 읽기는 둘 다, 쓰기는 .hwpx만 지원합니다. 내용을 파악만 할 문서라면 .hwp 그대로 써도 되지만, 수정할 문서라면 .hwpx로 시작해야 합니다.
엔진 + 어댑터 구조
hwp-mcp는 두 층으로 나뉩니다.
- 엔진 — rhwp: Edward Kim이 Rust와 WebAssembly로 만든 한글 포맷 처리 엔진입니다. 한글 파일을 실제로 해석하는 일꾼입니다.
- 어댑터 — hwp-mcp: 엔진 위에 AI가 자연어로 부를 수 있는 도구를 얹은 MCP 계층입니다. AI가 일꾼에게 말을 걸 수 있게 해주는 창구입니다.
WebAssembly는 운영체제와 관계없이 같은 방식으로 실행되는 실행 형식입니다. 기존 HWP 자동화 도구는 대부분 한컴 COM API(Windows 프로그램끼리 기능을 호출하는 방식) 기반이라 Windows 전용이었는데, hwp-mcp는 WebAssembly 덕분에 맥에서도 동작합니다. 제공 도구는 35개로 읽기/변환, 메타 조회, 페이지 렌더링(SVG), 텍스트 쓰기, 구조 편집, 서식, 이미지/표/신규 생성으로 나뉩니다.
비슷한 MCP와 비교
| 항목 | hwp-mcp (treesoop) | hwpx-mcp (Dayoooun) |
|---|---|---|
| 엔진 | rhwp (Rust+WASM) | TypeScript XML 직접 파싱 |
| .hwp 읽기 | O | X |
| 쓰기 | .hwpx만 | .hwpx만 |
| 도구 수 | 35개 | 77개 |
| 설치 | npx 한 줄 | git clone 후 빌드 |
| 작업 방식 | 파일 넣으면 결과 파일 (일회성) | 문서 열고 여러 번 편집 후 저장 (세션형) |
| 강점 | 읽기, 마크다운 변환, 템플릿 채우기 | 세밀한 서식, 각주, 수식, Undo/Redo |
정리하면 내용 파악과 양식 채우기는 hwp-mcp, 문서 꾸미기는 hwpx-mcp가 맞습니다.
설치 및 등록
Node 20 이상이 필요합니다.
node --version # v24.7.0
claude mcp add hwp-mcp --scope user -- npx -y hwp-mcp@latest
claude mcp list | grep hwp-mcp
# hwp-mcp: npx -y hwp-mcp@latest - ✔ Connected@latest를 붙인 이유가 있습니다. npx는 한 번 받은 패키지를 캐시에 남겨두는데, 캐시에 옛 버전(v0.2.0, 서버가 조용히 종료되는 버그가 있던 버전)이 남아 있으면 그것을 그대로 실행할 수 있습니다. @latest로 항상 최신 버전을 받도록 고정했습니다.
등록 후에는 세션을 새로 시작해야 도구가 로드됩니다. 또 Claude Code(CLI)와 Claude Desktop(GUI)은 MCP 등록이 별도이고, claude.ai 웹에서는 로컬 MCP가 동작하지 않습니다.
mkdir -p ~/hwp-practice && cd ~/hwp-practice
claude/mcp 화면에서 hwp-mcp 도구 35개가 보이면 준비 완료입니다.
/context로 컨텍스트 사용량 읽기
/context는 지금 컨텍스트 윈도우(AI가 한 번에 볼 수 있는 작업 공간)를 얼마나 쓰고 있는지 보여줍니다. 실습 환경(Opus 5.5)에서는 1M 토큰 중 66k(7%)를 쓰고 있었고, 화면의 칸 하나가 약 5k 토큰입니다.
눈여겨볼 점은 대화를 시작하기도 전에 깔려 있는 기본요금입니다. System prompt, System tools, MCP tools, Skills 등을 합쳐 약 42k였습니다. 등록된 MCP 도구가 227개나 되는데도 MCP tools는 6.7k에 불과했습니다. 도구 설명을 처음부터 전부 올리지 않고 필요할 때 불러오는 방식으로 추정됩니다. 오히려 Skills가 9.9k로 더 컸습니다. 토큰을 아끼고 싶다면 MCP를 줄이는 것보다 안 쓰는 플러그인을 정리하는 쪽이 더 효과적일 수 있습니다. 참고로 Autocompact buffer는 컨텍스트가 찼을 때 오래된 대화를 요약하는 자동 압축용 예약 공간입니다.
에이전트가 도구를 고르는 원리
Claude Code는 세션을 시작할 때 등록된 MCP 도구들의 설명서를 읽어둡니다. 사용자가 자연어로 요청하면 요청 내용과 설명서를 비교해 알맞은 도구를 스스로 고릅니다. 그래서 "hwp-mcp로"라고 말하지 않아도 한글 파일 요청이면 hwp-mcp 도구가 호출됩니다.
실습 1 — 생성·읽기·요약·변환
hello.hwpx 생성과 자동 도구 선택
hwp-mcp로 hello.hwpx 새 문서 만들어줘. '안녕 한글' 한 줄만 넣어줘create_hwpx_document로 문서가 생성됐습니다. 이어서 MCP 이름 없이 요청했습니다.
hello.hwpx 읽어줘Claude가 read_hwp를 스스로 골라 "안녕 한글"을 정상 출력했습니다.
실제 안내문 요약 — 없는 정보는 없다고 답하기
학교 보건진료소의 검진 안내문(.hwp)으로 "마감일, 지원 자격, 제출 서류만 정리해줘"라고 요청했습니다. Claude는 지원 자격은 정리했지만, 마감일과 제출 서류는 "문서에 없다"고 답했습니다. 그럴듯한 내용을 지어내는 할루시네이션(hallucination) 대신, 문서에 있는 검진 일시와 준비사항을 찾아 대신 제시했습니다. 요약할 항목을 구체적으로 지정하면 어떤 항목이 비어 있는지도 바로 드러난다는 장점이 있습니다.
마크다운 변환이 뭉개진 이유
같은 파일을 마크다운으로 변환해서 같은 이름의 .md로 저장해줘convert_hwp_markdown 결과는 예상과 달랐습니다. 2열 표 하나에 본문 전체가 한 칸, 한 줄로 들어가 있었습니다.
원인은 한국 공문서의 작성 습관에 있었습니다. 테두리를 치기 위해 문서 전체를 표 한 칸에 넣는 경우가 많습니다. hwp-mcp는 규칙대로 표를 마크다운 표로 바꿨는데, 마크다운 표의 칸 안에는 줄바꿈을 넣을 수 없어 내용이 한 줄로 뭉개진 것입니다.
그래서 역할을 나눴습니다. MCP로 정확하게 추출한 뒤, Claude에게 재구성을 맡겼습니다.
제목·소제목·목록 형태로 다듬어줘. 원본 내용은 하나도 빠뜨리지 말고, 표는 진짜 표 데이터일 때만 써줘- MCP: 한글 파일에서 내용을 정확하게 꺼내기
- Claude(LLM): 꺼낸 내용을 사람이 읽기 좋게 재구성하기
실습 2 — 템플릿 채우기와 조용한 실패
템플릿과 자리표시자
템플릿(template)은 반복해서 쓰는 양식이고, 자리표시자(placeholder)는 {{이름}}처럼 중괄호 두 개로 감싼 빈칸입니다. 양식을 한 번 만들어두면 값만 바꿔서 신청서를 계속 찍어낼 수 있습니다. hwp-mcp의 쓰기 도구는 기본적으로 원본을 덮어쓰지 않고 새 이름의 파일로 저장해 원본 양식을 보호합니다.
4단계를 한 번에 위임한 결과
에이전트에게 네 단계를 순서대로 맡겼습니다. 양식 생성 → 템플릿 채우기 → 다시 읽어서 검증 → .hwp 쓰기 시도입니다. 마지막 단계에는 "실패하면 우회하지 말고 에러를 그대로 보여줘"라는 조건을 걸었습니다.
| 단계 | 도구 | 결과 |
|---|---|---|
| 양식 만들기 | create_hwpx_document | 성공 (4줄이 문단 1개에 줄바꿈으로 들어감) |
| 채우기 | fill_hwp_template | 저장 완료 메시지, 그러나 0건 치환 |
| 검증 | read_hwp_text | {{이름}} 등이 그대로 남아 있음 |
| .hwp 쓰기 | replace_hwp_text | 실패 (.hwp 쓰기 미지원 에러) |
검증 단계가 잡아낸 조용한 실패
채우기 도구는 "저장 완료"라고 답했습니다. 검증 단계가 없었다면 성공한 줄 알고 넘어갔을 것입니다. 하지만 다시 읽어보니 {{이름}}이 그대로 남아 있었고, 치환은 0건이었습니다.
이런 현상을 조용한 실패(silent failure)라고 합니다. 에러 없이 성공처럼 끝났지만 실제로는 아무 일도 하지 않은 실패입니다. 반대로 .hwp 쓰기 실패는 에러 메시지가 원인과 해결책(.hwpx로 저장 후 시도)을 명확히 알려준 친절한 실패였습니다. 참고로 에러 문구에는 "v0.2"라고 나오지만 npm view hwp-mcp version 결과는 0.3.0이라 문구만 갱신되지 않은 것으로 보입니다.
가설 → 검증
양식 생성 결과에 단서가 있었습니다. create_hwpx_document가 4줄을 문단 4개가 아니라 줄바꿈이 섞인 문단 1개로 저장했습니다. 그래서 가설을 세웠습니다. "채우기 도구가 문단 하나에 섞인 {{…}}를 찾지 못하는 것이 아닐까?"
검증 방법은 단순했습니다.
- 한 줄짜리 양식을 생성
append_hwp_paragraph로 줄마다 별도 문단을 추가- 같은 방식으로 채우기 실행
결과는 총 3건 치환 성공이었고, 다시 읽어서 값이 들어간 것까지 확인했습니다. 내부 동작은 XML 구조를 보고 한 추정이지만, 문단을 분리하면 정상 동작한다는 것은 실험으로 확인했습니다.
중간에 쓰기 도구가 원본이 아닌 _appended 같은 새 파일에 저장하는 일도 있었습니다. 원본 보호를 위한 기본 동작인데, Claude가 이를 스스로 눈치채고 저장 위치를 원본 파일로 지정해 작업을 이어갔습니다.
교훈 — 성공 메시지를 믿지 말고 검증하라
- 도구의 "성공" 메시지는 결과가 아닙니다. 결과를 다시 읽어서 확인하는 단계를 프롬프트에 넣어야 합니다.
- Slack MCP 편에서
SLACK_TEAM_ID가 빠졌을 때 원인을 바로 알려주지 않던 것과 같은 유형입니다. - 한컴오피스에서 양식을 직접 만들 때도
{{이름}}은 한 번에 이어서 입력해야 합니다. 중간에 서식을 바꾸면 파일 속에서 글자가 쪼개져 저장되어 찾기가 실패할 수 있습니다.
실무 활용 시나리오
- 공고문 요약: 공모전·정부지원사업 공고문에서 마감일, 지원 자격, 제출 서류만 뽑아 정리합니다.
- 신청서 자동 작성:
{{}}템플릿 양식을 만들어두고 값만 바꿔 반복 생성합니다. 단, 채운 뒤 다시 읽어 검증하는 단계를 꼭 포함합니다. - 문서 아카이빙: 학교·공공 문서를 마크다운으로 변환해 Notion이나 Obsidian에 정리합니다.
마무리
이번 실습으로 맥에서 한컴오피스 없이 한글 문서를 읽고, 마크다운으로 변환하고, 양식까지 채워봤습니다. 동시에 초기 버전 도구의 조용한 실패를 검증 단계로 잡아내고, 가설을 세워 원인을 좁혀가는 과정을 경험했습니다.
다음에는 두 방향 중 하나를 이어가려 합니다. 이번에 찾은 조용한 실패의 재현 절차를 정리해 hwp-mcp GitHub에 이슈로 제보하는 오픈소스 기여, 또는 hwpx-mcp로 서식 편집까지 해보고 두 MCP를 비교하는 실습입니다.
