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

HWP·HWPX 한글 문서를 Claude Code·Claude Desktop·Cursor에서 바로 읽고 쓰는 오픈소스 MCP 서버 구축기. 한국 정부·공공기관·레거시 기업의 AI 도입 장벽이었던 HWP 파일 처리 문제를 한 줄 설치로 해결한 실전 가이드.

# 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에 안 들어가니까요.

HWP-MCP의 접근

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

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

기능

설명

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

설치는 한 줄

```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 파일 요약해줘"라고 요청하면 바로 읽어서 처리합니다.

실제 활용 사례

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

1. 기업 사내 RAG 챗봇

사내 지식을 RAG(Retrieval-Augmented Generation) 챗봇에 학습시킬 때 HWP 문서를 전처리 없이 파이프라인에 투입합니다. 구축 시간이 평균 30~40% 단축됐습니다.

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

공공 입찰은 RFP가 HWP로 배포됩니다. AI가 RFP를 직접 읽고 제안서 초안을 작성할 수 있게 되면서, 제안서 작성 시간이 줄었습니다.

3. 법무·계약 문서 검토

한국 로펌·법무팀의 계약서는 대부분 HWP. AI 검토 자동화가 이전에는 불가능했습니다. 이제는 AI가 계약서를 읽고 주요 조항, 리스크 포인트를 요약합니다.

4. 회의록 자동 작성

회의록을 HWP 템플릿으로 관리하는 기업이 여전히 많습니다. AI가 음성 회의록을 받아 HWP 템플릿을 자동으로 채웁니다.

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: 한컴 오피스가 꼭 설치되어 있어야 하나요?

A: 아닙니다. HWP-MCP는 한컴 라이선스와 무관하게 파일을 파싱합니다. 맥·윈도우 어디서든 동작합니다.

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

A: 네. HWP(구 바이너리 포맷)와 HWPX(XML 기반 신형식) 모두 지원합니다.

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

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

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

A: HWP-MCP는 로컬 실행 기본값입니다. 외부 서버로 문서를 보내지 않습니다. 온프레미스 배포에도 적합합니다.

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

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

---

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

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