클로드 한글(HWPX) 문서 만들기: hwpx-plugin 설치와 MCP
클로드로 한글(HWP·HWPX) 문서를 읽고 쓰려면 플러그인을 하나 깔아야 합니다. 앤트로픽의 업로드 지원 형식에 HWP·HWPX 가 없어서, 클로드 혼자서는 한글 파일을 열지 못하기 때문입니다. 지금 가장 손이 덜 가는 방법은 고규현(@airmang)이 공개한 hwpx-plugin 입니다. 클로드 코드에서 명령 두 줄로 깔고, 양식의 표와 서식은 그대로 둔 채 내용만 채우거나 공문서를 새로 만듭니다. 2026년 10월 현재 버전은 .hwpx 뿐 아니라 HWP 5.0 .hwp 도 직접 읽고 씁니다. 이 글은 2026년 10월 22일에 세 저장소의 README·CHANGELOG 와 한컴 공식 도움말을 읽고 확인한 내용만 적었습니다.
20초 영상으로 보기
두 영상이 이 글의 요약입니다. 첫 영상은 양식 하나가 새 한글 파일이 되는 길이고, 둘째 영상은 설치 순서입니다. 명령은 hwpx-plugins 저장소 README 에 적힌 그대로 옮겼습니다.
영상 1 자막 전문
- 첨부한 가정통신문 양식에서 학교명과 날짜만 바꿔 새 파일로 줘 (나 → AI)
- 양식과 바꿀 내용을 문장으로 줍니다
- 클로드 코드가 hwpx 스킬을 따라 순서를 정합니다
- MCP 도구가 표와 서식을 그대로 둔 채 글자만 바꿉니다
- 양식 채움·공문·신구대조표·상장을 만듭니다
- 미리보기는 근사치입니다. 제출 전에 한/글로 엽니다
- 개인정보는 넣기 전에 가립니다. 공식 저장소 github.com/airmang/hwpx-plugins · Apache-2.0
영상 2 자막 전문
- uv 를 설치합니다. Windows 는 아래 명령, macOS 는 uv 공식 설치 명령 명령: winget install --id=astral-sh.uv -e (첫 실행 때 Python 3.12 자동 설치)
- 마켓을 추가하고 플러그인을 설치합니다. 명령: claude plugin marketplace add airmang/hwpx-plugins (claude plugin install hwpx-plugin@hwpx)
- 새 세션을 열고 양식을 맡깁니다. 설치 뒤 새 세션에서 스킬과 도구가 잡힙니다 (양식 채움 · 공문서 · 사본에서 작업)
- 되는 일: .hwpx 와 HWP 5.0 .hwp읽기·쓰기·양식 채움. 안 되는 일: 암호·배포용·DRM 문서한컴과 같은 쪽 나눔 보장. 미리보기는 근사치입니다. 한/글로 직접 엽니다
한 장으로 보는 클로드 한글 문서
클로드는 한글 파일을 스스로 열지 못합니다. 앤트로픽의 업로드 지원 형식에 HWP·HWPX 가 없기 때문입니다. hwpx-plugin 은 스킬(작업 순서)과 MCP 서버(파일을 실제로 고치는 도구)를 한 묶음으로 넣어 이 빈칸을 메웁니다.
양식 파일과 바꿀 내용
어떤 도구를 어떤 순서로 쓸지
python-hwpx-automation
.hwpx · HWP 5.0 .hwp
출처: github.com/airmang/hwpx-plugins README, support.claude.com/ko 8241126 업로드 형식 (2026-07-23)
HWP 와 HWPX 는 무엇이 다른가
HWP 는 한/글의 옛 바이너리 형식이고, HWPX 는 XML 파일 여러 개를 ZIP 으로 묶은 개방형 형식입니다. HWPX 는 2011년 12월 30일 제정된 한국산업표준 KS X 6101(OWPML)을 바탕으로 하고, 한컴은 2021년부터 HWPX 를 기본 저장 형식으로 썼습니다. 확장자를 .zip 으로 바꾸면 압축이 풀릴 만큼 구조가 열려 있어서, AI 도구가 다루기 쉬운 쪽은 HWPX 입니다.
가지고 있는 파일이 .hwp 라면 한/글에서 바꿔 두는 편이 안전합니다. 한 파일은 [파일-다른 이름으로 저장하기](Alt+V)에서 파일 형식을 한/글 표준 문서(*.hwpx) 로 고릅니다. 기본 저장 형식은 도구 > 환경설정 > 파일 에서 바꿉니다. 여러 파일은 한컴닷컴 다운로드 센터의 무료 "HWPX 변환기" 가 한 번에 30개씩 바꿉니다.
설치하는 법: 클로드 코드 기준
1. uv 를 설치합니다. README 는 "uv 가 설치되어 있어야 MCP 서버가 시작됩니다" 라고 적습니다. 첫 실행 때 플러그인이 Python 3.12 를 스스로 내려받으므로 파이썬을 따로 깔 필요는 없습니다.
2. 마켓을 추가하고 플러그인을 설치합니다.
3. 새 세션을 엽니다. 설치한 세션에서는 스킬과 도구가 잡히지 않습니다. 첫 실행이 오래 걸려 시간 초과가 나면 MCP_TIMEOUT=60000 claude 처럼 시작 제한을 늘립니다. 업데이트는 아래 한 줄입니다.
코덱스에서는 codex plugin marketplace add airmang/hwpx-plugins 뒤 codex plugin add hwpx-plugin@hwpx 를 실행합니다. 커서는 스킬 파일을 .cursor/skills/hwpx/ 에 복사합니다.
어디서 되나: 클로드 환경별 차이
| 환경 | 스킬 | MCP 도구 | 참고 |
|---|---|---|---|
| 클로드 코드 (터미널·IDE·데스크톱 Code 탭) | 됨 | 됨 | 이 글의 기준. 기능을 다 씁니다 |
| 코워크 | 됨 | 조건부 | 세션이 내 컴퓨터에서 돌 때만 MCP 를 읽습니다. 10월 6일부터 Pro·Max 의 새 작업은 클라우드에서 돕니다 |
| claude.ai·데스크톱 채팅·모바일 | 됨 | 무시됨 | 스킬에 동봉한 엔진으로 돕니다(코드 실행 환경에 lxml 필요). CHANGELOG 의 [Unreleased] 항목입니다 |
클로드 데스크톱 앱의 채팅에 MCP 서버만 따로 붙이고 싶다면 claude_desktop_config.json 에 아래를 넣습니다. HWPX_AUTOMATION_WORKSPACE_ROOTS 를 비워 두면 앱이 서버를 시스템 폴더에서 띄워 모든 문서 경로가 막힌다고 README 가 경고합니다. 예시의 버전 고정(7.3.1)은 README 원문 그대로이고, 2026년 10월 22일 PyPI 최신은 7.3.4 입니다.
한글 문서용 MCP·스킬 지도
깃허브에서 "hwpx mcp" 와 "hwp mcp" 로 찾은 저장소를 별 수 순서로 놓았습니다. 별 수는 2026년 10월 22일 오전에 잰 값입니다. 하는 일과 필요한 환경이 저마다 다릅니다.
HWP·HWPX·PDF·오피스를 마크다운으로 바꾸고 양식을 채웁니다. MIT
읽기·변환 중심설치된 한/글 프로그램을 COM 으로 움직입니다. MIT
Windows + 한/글 필요스킬과 MCP 묶음. 엔진은 python-hwpx(별 117)·automation(별 68). Apache-2.0
이 글의 기준Rust·WASM 기반, 도구 35개. 쓰기는 .hwpx 만. MIT
Node 20 이상업스테이지가 만든 공문서 생성기. 보고서·보도자료·기안문. MIT
공문서 전용한/글 안에서 외부 도구를 MCP 로 부르는 기능. 지금은 노션만 연결
방향이 반대출처: 각 저장소 README·LICENSE, GitHub 검색 (2026-10-22 09:47 KST), help.hancom.com AI 에이전트 실험실
이렇게 맡기십시오: README 예시 프롬프트
양식 채움은 analyze_form_fill 로 빈칸을 찾고, apply_form_fill 로 채우고, verify_form_fill 로 원본 서식이 그대로인지 검사하는 세 단계로 돕니다. 공문은 compose_official_draft(별지 제1호 기안문), 비교표는 doc_diff(신구대조표), 상장은 mail_merge 가 맡습니다. 이름은 스킬이 알아서 고르므로 외울 필요는 없습니다.
숫자로 보는 hwpx-plugin
출처: hwpx-plugins CHANGELOG, python-hwpx README, 한컴 FAQ 3128, 한컴테크 블로그 (2025-02-26)
쓰기 전에 지킬 네 가지
- 사본에서 작업합니다. README 원문은 "수정 도구는 호출 즉시 저장되므로 검토용 작업은 반드시 사본에서 하세요" 입니다. 자동 백업(
.bak)이 기본으로 켜져 있지만 믿지 않는 편이 낫습니다. - 개인정보는 미리 가립니다. 읽기 도구는 개인정보 가림(
mask=true)이 기본이지만, 양식 채움과 메일머지에는 가림 옵션이 없다고 문서가 밝힙니다.scan_personal_info로 먼저 찾아보십시오. - 제출 전에 한/글로 엽니다. 내장 미리보기는 텍스트 근사치이고, 쪽 나눔과 표 맞춤이 한컴과 다를 수 있습니다. 한컴과 같은 렌더는 macOS 한컴오피스 한글이나 Windows 한글이 깔린 컴퓨터에서만 됩니다.
- 암호·배포용·DRM 문서는 맡기지 않습니다. 엔진이 지원하지 않고, 숨기지 않고 오류로 알립니다. 회사 문서보안 프로그램이 HWPX 를 못 읽으면 한컴 FAQ 대로 HWP 로 다시 저장합니다.
되는 일과 안 되는 일
- 양식은 그대로 두고 빈칸만 채우기 (바이트 보존)
- 공문·보고서·가정통신문 새로 만들기, 별지 제1호·제2호 기안문
- 신구대조표, 상장·수료증 메일머지, 표 계산
- 개인정보 찾기, 깨진 .hwpx 복구, 변경 추적
- HWP 5.0 .hwp 직접 읽고 다시 쓰기
- 암호 걸린 문서, 배포용 문서, DRM 문서
- 그림 뒤집기·회전
- 한컴과 똑같은 쪽 나눔 보장 (미리보기는 근사치)
- claude.ai 채팅에서 MCP 쓰기 (스킬 동봉 엔진만 동작)
- 양식 채움·메일머지의 개인정보 자동 가림
출처: hwpx-plugins·python-hwpx·python-hwpx-automation README "알려진 제약", references/workflows-pii.md
챗GPT·한컴은 어떻게 하고 있나
언론 보도에 따르면 OpenAI 는 2026년 4월 17일 챗GPT 에서 HWP·HWPX 파일을 올려 요약하고 묻는 기능을 발표했습니다. 이는 읽기 기능이고, OpenAI 영문 도움말(10월 6일 갱신)의 형식 표에는 HWP 가 아직 없습니다. 한컴은 공식 MCP 서버를 내지 않았습니다. 한/글 안의 "AI 에이전트 실험실" 은 한/글이 외부 도구를 부르는 기능이라 방향이 반대이고, 지금 연결되는 도구는 노션뿐입니다. 기업용 "한컴 에이전틱 OS" 는 2026년 9월 1일 데모를 열었습니다.
업무용 문서 스킬을 더 찾는다면 회사 메일·보고서 쓰는 Claude 스킬을, 플러그인 설치가 막히면 클로드 MCP 연결 오류 해결을 보십시오.
자주 묻는 질문
claude mcp add korean-report-hwpx -- uvx korean-report-hwpx).출처
- 저장소: airmang/hwpx-plugins, airmang/python-hwpx, airmang/python-hwpx-automation, PyPI python-hwpx-automation
- 비교: kordoc, jkf87/hwp-mcp, treesoop/hwp-mcp, korean-report-hwpx
- 한컴: 다른 이름으로 저장하기 도움말, HWP·HWPX FAQ, HWPX 변환기 FAQ, 한컴테크 HWPX 구조, AI 에이전트 실험실
- 공공 보안: 국정원 AI보안 가이드북 v2.0 (2025-12-10), 행정안전부 생성형 AI 이용 안내 (2025-02-07)
- 업로드 형식: 클로드 지원 파일 형식 (2026-07-23), 연합뉴스 챗GPT HWP 지원 보도 (2026-04-17)