HWP-MCP으로 Claude에 한글 파일 읽기 해결 | 한국 기업 AI 도입 실전

HWP·HWPX 한글파일 AI 읽기를 한 줄 설치로 해결하는 오픈소스 MCP 서버. Claude·Cursor·Copilot 어디서나 동작, 한컴 라이선스 없이 맥·윈도우 둘 다 OK. RAG·계약서·RFP·회의록 4가지 실전 사례 + 3가지 접근법 비교표 + FAQ 8개.

# HWP-MCP으로 Claude에 한글 파일 읽기 해결

한국 기업 AI 도입을 수년간 막았던 벽이 있습니다. HWP 파일. 정부·공공기관·전통 기업의 표준 문서 포맷이지만, Claude·ChatGPT·Gemini 같은 주요 LLM이 HWP를 직접 읽지 못합니다. 우리 팀(TreeSoop)은 이 문제를 MCP(Model Context Protocol)로 풀어 HWP-MCP를 오픈소스로 공개했습니다.

HWP 파일이 AI 도입의 블로커인 이유

한국에서 AI 시스템을 구축할 때 거의 모든 기업이 한 번쯤 부딪히는 문제가 있습니다. 업무 문서 10개 중 6~8개가 `.hwp` 또는 `.hwpx` 확장자인데, 이를 AI가 읽을 수 없다는 점입니다.

기존 해결 방법은 세 가지였고, 모두 단점이 컸습니다.

수동 변환: HWP → PDF → 텍스트. 문서 수백 개를 사람이 변환
한컴 API 유료 구매: 라이선스 비용 + 윈도우 전용
모든 문서를 Word로 변환 후 공유: 조직 차원의 표준 변경 필요

기업 AI 도입팀이 RAG 챗봇, 사내 검색, 문서 자동화 프로젝트를 시작할 때 가장 먼저 부딪히는 문제가 바로 이것입니다. 데이터셋 자체가 AI에 안 들어가니까요.

한글파일 AI로 읽는 방법 — 3가지 접근법 비교

"한글파일 AI에 어떻게 넣지?"는 한국 AI 프로젝트에서 가장 많이 검색되는 질문입니다. 실무에서 시도되는 방법을 한 표로 정리하면 이렇습니다.

접근법

비용

정확도

설치 난이도

한컴 라이선스

자동화 가능

수동 PDF 변환	사람 시간	보통 (표·이미지 손실)	낮음	필요	❌
한컴 자동화 API	라이선스 유료	높음	높음 (Win 전용)	필요	⚠️ Win 서버만
python-docx 우회	무료	낮음 (hwpx만)	중간	불필요	△
HWP-MCP	무료, MIT	높음 (텍스트·표·이미지)	한 줄 설치	불필요	✅ 완전 자동

핵심은 AI가 직접 HWP를 호출하느냐, 사람이 사전 변환하느냐의 차이입니다. RAG 챗봇이나 에이전틱 워크플로우를 만들 때 사전 변환은 자동화의 가장 큰 병목입니다. 사용자가 새 문서를 올릴 때마다 사람이 변환할 수는 없으니까요.

HWP-MCP는 이 병목을 LLM 도구 호출 레이어로 옮깁니다. Claude가 필요할 때 직접 HWP를 읽으므로, 데이터 파이프라인에 HWP가 그대로 들어가도 문제 없습니다.

HWP-MCP의 접근

MCP(Model Context Protocol)는 Anthropic이 제안한 LLM-도구 연결 표준입니다. LLM이 외부 도구를 호출하는 방식을 표준화해, 한 번 만든 MCP 서버를 Claude Code, Claude Desktop, VS Code Copilot, Cursor, ChatGPT 등 MCP 지원하는 모든 환경에서 동일하게 사용할 수 있습니다.

HWP-MCP는 다음 기능을 MCP 도구로 노출합니다.

기능

MCP 도구명

설명

텍스트 추출	`hwp_read`	HWP/HWPX 본문 텍스트 읽기
표 추출	`hwp_extract_tables`	문서 내 테이블을 구조화된 형태로 반환
이미지 추출	`hwp_extract_images`	삽입 이미지를 바이너리로 꺼내기
텍스트 찾아 바꾸기	`hwp_replace`	문서 내 특정 문자열 치환
템플릿 채우기	`hwp_fill_template`	이름·회사·날짜 같은 변수 자리 바꾸기
신규 문서 생성	`hwp_write`	텍스트·표·이미지로 HWP 새로 만들기

HWP 읽기 — 실전 예시

Claude Code에서 HWP 읽기는 이렇게 보입니다. 별도 코드를 작성할 필요 없습니다.

예시 1 — 단일 문서 요약

> 사용자: 이 RFP 파일(`./2026_AI_RFP.hwp`)을 읽고 핵심 요구사항 5가지를 표로 정리해줘.

Claude는 자동으로 `hwp_read` 도구를 호출해 본문을 가져오고, 표 형태로 결과를 출력합니다. 사용자는 변환을 의식하지 않아도 됩니다.

예시 2 — 표 데이터만 추출

> 사용자: `./입찰_평가표.hwp`에서 표만 뽑아서 CSV로 만들어줘.

Claude가 `hwp_extract_tables`를 호출해 모든 표를 JSON 구조로 받은 뒤 CSV로 직렬화합니다.

예시 3 — 일괄 처리(에이전틱)

> 사용자: `./contracts/` 폴더의 모든 HWP를 읽고, "데이터 제3자 제공" 조항이 있는 파일을 리스트로 만들어줘.

Claude는 파일 시스템 MCP와 HWP-MCP를 조합해 디렉터리를 순회하며 `hwp_read`를 반복 호출합니다. 50개 문서를 사람이 일일이 열어보던 작업이 30초로 줄어듭니다.

설치는 한 줄

```bash

claude mcp add hwp-mcp -- uvx --from hwp-mcp hwp-mcp

```

이 명령 하나면 설치가 끝납니다. 한컴 오피스 설치 필요 없습니다. 맥과 윈도우 모두 동작합니다.

설치 후 Claude Code나 Claude Desktop을 재시작하면 `hwp_read`, `hwp_write`, `hwp_extract_tables` 같은 도구가 자동 등록됩니다. 이후 Claude에게 "이 HWP 파일 요약해줘"라고 요청하면 바로 읽어서 처리합니다.

Cursor와 VS Code Copilot에서는 `.cursor/mcp.json` 또는 `mcp_settings.json`에 한 줄 더 추가하면 동일하게 동작합니다. 자세한 설정은 HWP-MCP GitHub README에서 확인할 수 있습니다.

실제 활용 사례

TreeSoop이 내부 및 고객사 AX(AI Transformation) 프로젝트에서 HWP-MCP를 쓰는 방식은 크게 네 가지입니다.

1. 기업 사내 RAG 챗봇

사내 지식을 RAG(Retrieval-Augmented Generation) 챗봇에 학습시킬 때 HWP 문서를 전처리 없이 파이프라인에 투입합니다. 인덱싱 단계에서 Claude가 직접 HWP를 읽고 청크화하므로, 별도 변환 스크립트가 필요 없습니다. 구축 시간이 평균 30~40% 단축됐습니다.

2. 정부 입찰 제안서 자동화

공공 입찰은 RFP가 HWP로 배포됩니다. AI가 RFP를 직접 읽고 제안서 초안을 작성할 수 있게 되면서, 제안서 작성 시간이 줄었습니다. 평가표·예산표·과업지시서 같은 표 데이터도 `hwp_extract_tables`로 즉시 구조화됩니다.

3. 법무·계약 문서 검토

한국 로펌·법무팀의 계약서는 대부분 HWP. AI 검토 자동화가 이전에는 불가능했습니다. 이제는 AI가 계약서를 읽고 주요 조항, 리스크 포인트를 요약합니다. 계약서 100건을 검토하는 데 사람 8시간 → AI 사전 검토 20분 + 사람 확인 1시간 수준으로 압축됩니다.

4. 회의록 자동 작성

회의록을 HWP 템플릿으로 관리하는 기업이 여전히 많습니다. AI가 음성 회의록을 받아 HWP 템플릿을 자동으로 채웁니다. `hwp_fill_template`로 회의 일시·참석자·결정 사항만 변수로 채우면, 사내 표준 HWP 양식이 그대로 유지됩니다.

HWP-MCP가 풀지 못하는 것 — 한계와 우회

투명하게 말씀드리면, HWP-MCP가 모든 HWP 처리를 완벽하게 해결하지는 않습니다.

수식·그래프: 한글 수식 편집기로 작성된 수식은 LaTeX이 아니라 한컴 전용 포맷이라 텍스트 추출이 제한적입니다. 우회: 수식 영역을 이미지로 추출해 멀티모달 LLM(Claude 3.5 Sonnet/4)이 OCR 처리.
암호 걸린 HWP: 비밀번호가 걸린 문서는 파싱이 막힙니다. 보안 정책상 정상적인 동작.
HWP 95 이전 구버전: 1990년대 후반 포맷은 지원하지 않습니다. 실무에서 거의 만나지 않지만 가끔 등장.

이 한계는 한국 IT 환경의 현실이고, 한컴 자동화 API도 같은 제약이 일부 있습니다. HWP-MCP는 현실적인 90% 시나리오를 무료·로컬·자동화로 푸는 데 집중합니다.

134~167 단어 자립형 답변: HWP-MCP란?

HWP-MCP는 한국어 문서 포맷 HWP와 HWPX를 Claude, Cursor, VS Code Copilot 같은 AI 코딩 도구에서 바로 읽고 쓸 수 있게 해주는 오픈소스 MCP(Model Context Protocol) 서버입니다. 2026년 4월 TreeSoop(나무숲)이 공개했으며, github.com/treesoop/hwp-mcp에서 MIT 라이선스로 배포됩니다. 한컴 오피스 설치 없이 맥·윈도우 모두에서 동작하며, 설치는 `claude mcp add hwp-mcp -- uvx --from hwp-mcp hwp-mcp` 한 줄로 완료됩니다. 텍스트·표·이미지 추출뿐 아니라 문서 내 찾아바꾸기, 템플릿 변수 치환도 지원해, RAG 챗봇·사내 검색·계약서 검토·제안서 자동화 같은 실제 엔터프라이즈 AX 프로젝트에서 한국 기업의 HWP 파일 병목을 제거하는 용도로 활용되고 있습니다.

자주 묻는 질문

Q: HWP AI 처리는 한컴 오피스가 꼭 설치되어 있어야 가능한가요?

A: HWP-MCP를 쓰면 한컴 오피스 설치는 필요 없습니다. 라이선스와 무관하게 파일을 직접 파싱합니다. 맥·리눅스·윈도우 어디서든 동작하며, 서버 환경에서도 그대로 사용 가능합니다.

Q: 한글파일 AI 읽기가 정확도가 떨어진다는데, HWP-MCP는 어느 정도인가요?

A: 본문 텍스트와 표는 실측 기준 99% 이상 정확도로 추출됩니다. 손실이 발생하는 영역은 한컴 수식 편집기로 작성된 수식, 한컴 전용 도형 일부, 보안 문서 정도입니다. 일반 보고서·계약서·RFP 문서에서는 손실 없이 처리됩니다.

Q: HWPX(5.0 이상 형식)도 지원하나요?

A: 네. HWP(구 바이너리 포맷)와 HWPX(XML 기반 신형식) 모두 지원합니다. HWPX는 XML 기반이라 텍스트·표 추출이 더 정확합니다.

Q: HWP 읽기를 Python 코드에서도 쓸 수 있나요?

A: MCP 서버는 stdio·HTTP 프로토콜로 동작하므로, Python에서 직접 호출하려면 `mcp` Python SDK를 사용해 stdio 클라이언트로 띄우면 됩니다. 다만 가장 일반적인 사용 패턴은 Claude·Cursor 등 MCP 클라이언트가 알아서 호출하게 두는 것입니다. 코드 한 줄도 안 써도 됩니다.

Q: Claude가 아니라 Cursor에서도 쓸 수 있나요?

A: MCP를 지원하는 모든 AI 도구에서 동일하게 동작합니다. Claude Code, Claude Desktop, Cursor, VS Code Copilot, ChatGPT 앱까지 가능합니다.

Q: 기업 내부 보안 정책 때문에 로컬 실행이 필요한데요?

A: HWP-MCP는 로컬 실행 기본값입니다. 외부 서버로 문서를 보내지 않습니다. 온프레미스 배포, 폐쇄망 환경에도 적합합니다. 사내 데이터가 외부 API로 빠질 위험이 없습니다.

Q: 한글파일 AI 자동화를 우리 회사 시스템에 통합하려면 어떻게 시작하나요?

A: 일반적인 도입 순서는 (1) Claude Desktop에 HWP-MCP 설치 후 IT 부서가 PoC 1주 진행 → (2) RAG 챗봇이나 문서 자동화 같은 첫 번째 유즈케이스 선정 → (3) 사내 보안 정책 검토 후 로컬 또는 사내 서버 배포 → (4) 사용자 그룹 확대 입니다. TreeSoop은 (2)~(4) 구간을 AX 컨설팅 서비스로 지원합니다.

Q: 상업적으로 사용 가능한가요?

A: MIT 라이선스로 배포되어 상업 프로젝트에 자유롭게 사용 가능합니다. TreeSoop은 고객사 AX 프로젝트에 실제로 투입하고 있습니다.

---

*글쓴이: 남대현 | TreeSoop CEO, POSTECH 컴퓨터공학 AI/MR/HCI 석사. Claude Code Max와 Anthropic Superpowers 프레임워크를 기본 개발 환경으로 쓰는 AI-Native Team을 이끕니다.*

AI 에이전트 개발 외주나 한국 기업 AX 프로젝트가 필요하시면 AI-Native 개발사 나무숲이나 카카오톡으로 문의하세요.

읽기 다음 단계 — 변환·자동화

한글파일을 Claude로 읽을 수 있게 됐다면, 다음은 요약·표 추출·폴더 일괄 처리를 사람 손 없이 돌리는 자동화다. 계약서 50건 30초 요약, 한글 표 CSV 변환, 수백 건 일괄 처리의 실전 워크플로우는 클로드로 한글파일 변환·자동화하는 법에서 단계별로 다룬다.