"HWP-MCP 깔았는데 왜 한글 프로그램이 없다고 에러가 나지?" 혹은 반대로 "한글 프로그램도 없는데 이게 왜 돼?" — HWP-MCP를 검색해서 들어온 분이라면 둘 중 하나의 궁금증을 안고 왔을 겁니다. 결론부터 말하면 둘 다 맞는 말입니다. HWP-MCP라는 이름을 쓰는 프로젝트가 GitHub에 여러 개 있고, 그중 어떤 걸 설치했느냐에 따라 답이 정반대로 갈리거든요. 이 글에서는 어떤 프로젝트가 있는지, 내 상황(한컴오피스 있음/없음, OS)에 맞는 선택지가 뭔지 정리해봤습니다.
HWP-MCP, 사실 하나가 아니다
저도 처음엔 "HWP-MCP"를 검색하면 나오는 첫 번째 저장소만 보고 "아, 이거구나" 했는데, 알고 보니 GitHub에 같은 이름의 서로 다른 프로젝트가 최소 두 개, 관련 프로젝트까지 합치면 다섯 개 넘게 있더군요. 개발자도 다르고, 구현 언어도 다르고, 심지어 한컴오피스가 필요한지 아닌지도 반대입니다.
대표적으로 jkf87/hwp-mcp(Python, 스타 259개)와 treesoop/hwp-mcp(TypeScript, 스타 51개)가 이름이 완전히 똑같습니다. 여기에 HWPX 전용인 airmang/hwpx-mcp-server(스타 62개), 세부 제어 기능이 많은 crowwan/hwp-mcp-advanced-custom, Go로 짠 m1ns2o/hwp-mcp-go 같은 프로젝트까지 있습니다. 전부 2025~2026년 사이에 만들어진 개인·소규모 개발팀 프로젝트고, 한글과컴퓨터가 공식으로 만든 건 하나도 없습니다.
그러니까 "HWP-MCP 설치법"을 검색해서 나온 글을 그대로 따라 했는데 안 된다면, 애초에 다른 프로젝트 얘기를 보고 있었을 가능성부터 의심해봐야 합니다.
한컴오피스 설치가 필요한가 — 프로젝트마다 답이 다르다
이게 이 글에서 제일 중요한 부분입니다. HWP-MCP를 쓰려면 한글(한컴오피스) 프로그램이 PC에 깔려 있어야 하냐는 질문, 답은 "어느 프로젝트를 쓰느냐에 따라 다르다"입니다.
이미 한컴오피스가 깔려 있는 Windows 사용자 → jkf87/hwp-mcp
jkf87/hwp-mcp는 pywin32 기반 COM 자동화 방식입니다. 쉽게 말해 한글 프로그램을 실제로 백그라운드에서 실행시켜놓고 Claude가 그 프로그램을 원격 조종하는 구조예요. 그래서 Windows여야 하고, 한글 프로그램이 실제로 설치되어 실행 가능한 상태여야 동작합니다. README에는 문서 생성, 텍스트 삽입, 글꼴 설정, 표 생성과 데이터 채우기, 여러 작업을 순서대로 실행하는 배치 기능이 있다고 나와 있습니다.
설치는 git clone https://github.com/jkf87/hwp-mcp.git 후 pip install -r requirements.txt, 그다음 Claude Desktop 설정 JSON에 Python 스크립트 경로를 직접 적어주는 방식입니다.
{
"mcpServers": {
"hwp": {
"command": "python",
"args": ["경로/hwp-mcp/hwp_mcp_stdio_server.py"]
}
}
}한글 프로그램의 외부 파일 접근 보안 경고를 우회하는 DLL 모듈도 포함돼 있는데, 반대로 말하면 한글 프로그램이 안 켜져 있으면 연결 자체가 실패할 수 있다는 뜻이기도 합니다. 이미 회사·관공서 PC에 한컴오피스가 깔려 있고 Windows만 쓴다면 가장 직관적인 선택지입니다.
한컴오피스 없이 크로스플랫폼으로 쓰고 싶다 → treesoop/hwp-mcp
treesoop/hwp-mcp는 완전히 다른 접근입니다. Rust/WebAssembly로 만든 자체 HWP 파싱 엔진 rhwp 위에 34개 도구를 얹은 구조라, 한글 프로그램 없이 macOS·Windows·Linux 어디서나 동작한다고 README에 명시돼 있습니다. 설치도 claude mcp add hwp-mcp -- npx -y hwp-mcp 한 줄이면 끝이라 훨씬 간단하고요.
다만 함정이 하나 있습니다. 읽기(문서 내용·표·이미지 추출, SVG/HTML 렌더링)는 .hwp와 .hwpx 둘 다 되는데, 쓰기(텍스트 치환, 템플릿 채우기, 문단/표 추가)는 .hwpx 포맷에서만 지원됩니다. 기존 구버전 .hwp 파일을 열어서 내용을 편집하려는 거라면 이 프로젝트로는 안 될 수 있다는 얘기죠.
HWPX 문서만 다루면 된다 → airmang/hwpx-mcp-server
애초에 다루는 문서가 최신 개방형 포맷인 .hwpx뿐이라면 airmang/hwpx-mcp-server도 대안입니다. 순수 파이썬 라이브러리 python-hwpx 위에서 동작해서 한컴오피스가 필요 없고, Windows·macOS·Linux 모두 지원합니다. uvx hwpx-mcp-server 명령으로 바로 설치되고, 열람·검색·편집·양식 채움·문서 생성까지 지원합니다. 다만 이름 그대로 .hwpx만 대상이고 바이너리 .hwp는 처음부터 편집 대상이 아니라고 README에 못 박혀 있어서, 옛날 .hwp 문서가 많다면 이건 선택지에서 빠집니다.
그 외 HWP-MCP 후보군 — 더 있다
여기까지가 널리 쓰이는 세 개고, 그 외에도 crowwan/hwp-mcp-advanced-custom(Windows COM 기반, 59개 이상의 세부 제어 기능, 스타 6개), Dayoooun/hwpx-mcp(스타 27개), m1ns2o/hwp-mcp-go(Go로 짠 Windows 전용, 스타 2개) 같은 프로젝트도 검색에서 확인됩니다.
crowwan 프로젝트는 README에서 스스로 한계를 인정하는 부분이 눈에 띄었는데, 한글 파일을 여러 개 동시에 열면 각각 별도 프로세스로 뜨지만 COM은 한 프로세스에만 연결되기 때문에 다중 문서 작업에는 제약이 있다고 직접 경고해두고 있습니다. Dayoooun과 m1ns2o 프로젝트는 스타·포크 수가 적어서 아직 커뮤니티에서 검증된 규모는 크지 않다고 보는 게 맞습니다.
HWP-MCP로 실제로 뭘 할 수 있나
프로젝트마다 기능 범위는 다르지만, 공통적으로 확인되는 작업을 묶어보면 이렇습니다.
- 문서 생성·열기·저장·닫기
- 텍스트 삽입과 글꼴·문단·페이지 서식 설정
- 표 생성, 셀 데이터 채우기, 연속 번호 자동 채우기
- 찾기/바꾸기,
{{이름}}{{날짜}}같은 템플릿 변수 채우기 - 본문·표·이미지·머리말·꼬리말·각주·수식 추출, 문서 메타정보(버전, 페이지 수, 글꼴) 조회
- 여러 작업을 순서대로 묶어 실행하는 배치 처리
이 중 "템플릿 채우기"와 "표에 데이터 채우기"가 실무에서 제일 쓸모 있는 조합이라고 생각합니다. 보고서 양식 하나 만들어두고 Claude한테 "이 표에 이번 분기 매출 데이터 채워줘" 하는 식으로 시키면 되니까요.
HWP-MCP 한계와 실사용 후기, 그런데 걸러 들어야 할 부분도 있다
TreeSoop 자사 블로그(개발사 측 설명)에 따르면 한글 수식 편집기로 만든 수식은 텍스트 추출이 제한적이고, 비밀번호 걸린 문서는 파싱이 막히며, 1990년대 후반의 구버전 HWP 포맷은 아예 지원하지 않는다고 합니다. 검색어가 두 텍스트 노드에 걸쳐 있으면 매칭이 안 되는 것도 알려진 한계입니다. 다만 이건 프로젝트 운영사가 직접 쓴 홍보성 글이라 독립적인 제3자가 검증한 내용은 아니라는 점, 감안하고 읽어야 합니다.
"공공기관의 91%가 한컴오피스를 쓰는데 AI는 HWP를 제대로 못 읽는다"는 문제의식은 실제 현장에서도 확인됩니다. 웹진 인벤(2026-04-20)에 따르면 광진구청 소속 7년 차 공무원이 이 문제를 직접 겪고 HWP/HWPX/PDF를 AI가 읽을 수 있게 변환하는 도구를 직접 만들어 공개한 사례가 있습니다. hwp-mcp 계열 프로젝트에 대한 후기는 아니지만, 문제 자체가 현장에서 실제로 겪는 일이라는 근거는 됩니다.
HWP를 여전히 많이 쓰는 이유, 그런데 흐름이 바뀌고 있다
1990년대 초 정부가 HWP를 공문서 표준 포맷으로 지정한 이래로 행정 전산망과 전자결재 시스템 대부분이 이 형식 기반으로 굳어졌습니다. 직원들이 익숙한 양식으로 문서를 올리고 결재받을 수 있고, 글자 겹치기·페이지 보호 같은 한글 전용 기능이 기존 그룹웨어와 궁합이 좋다는 점이 배경입니다.
근데 최근 이 흐름에 제동이 걸렸습니다. 국가인공지능전략위원회가 2026년 4월 24일 행정안전부·문화체육관광부와 함께 공공 문서 유통망에서 바이너리 HWP 사용을 단계적으로 제한하고 개방형 포맷 HWPX로 전환하는 방침을 발표했거든요. 행정 전산망은 5월 18일부터 지자체로 HWPX 적용을 확대했고, 공무원 메일 시스템은 10월까지 전환을 완료할 계획입니다. AI가 기존 바이너리 HWP는 구조상 데이터를 잘 못 뽑아내는데, HWPX는 문서 구성요소가 구조화돼 있어서 AI 활용도가 높다는 게 정부 판단입니다. 이 흐름을 보면 HWPX 전용으로 만들어진 airmang/hwpx-mcp-server 같은 프로젝트의 존재 가치가 앞으로 더 커질 가능성이 있어 보입니다.
결국 어떤 HWP-MCP를 골라야 하나
결론부터 말하면 이렇습니다.
- Windows + 한컴오피스가 이미 깔려 있고, 기존
.hwp파일을 직접 편집해야 한다 →jkf87/hwp-mcp - 한컴오피스 없이 macOS·Linux에서도 쓰고 싶다, 읽기 위주 작업이 많다 →
treesoop/hwp-mcp - 다루는 문서가 전부
.hwpx고 크로스플랫폼이 필요하다 →airmang/hwpx-mcp-server - 한글 COM 자동화로 더 세밀한 서식 제어가 필요하다 →
crowwan/hwp-mcp-advanced-custom(단, 다중 문서 동시 작업 제약 있음)
세 가지 질문만 스스로 던져보면 답이 나옵니다. 한컴오피스가 설치돼 있는가, OS가 뭔가, 다루는 파일이 .hwp인가 .hwpx인가.
자주 묻는 질문
Q. HWP-MCP 설치했는데 Claude가 도구를 인식 못 해요.
세션을 재시작해야 새로 등록한 MCP 도구가 보이는 경우가 많습니다. treesoop/hwp-mcp README는 claude mcp list | grep hwp-mcp 실행 시 ✓ Connected가 뜨는지부터 확인하라고 안내합니다.
Q. jkf87/hwp-mcp를 설치했는데 연결이 안 돼요.
한글 프로그램이 실제로 실행 중이어야 COM 연결이 됩니다. 한글 프로그램을 먼저 켜둔 상태에서 다시 시도해보세요.
Q. 회사 문서를 외부로 안 보내고 싶은데 안전한가요?
treesoop/hwp-mcp README는 로컬 실행이 기본값이라 문서를 외부 서버로 전송하지 않는다고 설명합니다. 다만 이 역시 프로젝트 측 자체 설명이니 폐쇄망 환경이라면 소스 코드를 직접 확인해보는 걸 권합니다.
한컴오피스 유무, OS, 다루는 파일 포맷 세 가지만 확인하면 어떤 프로젝트를 설치해야 할지는 이미 정해진 셈입니다. 직접 설치해보고 막히는 부분이 있으면, 이 글에서 다룬 세 프로젝트 중 어떤 걸 썼는지부터 다시 확인해보세요. 대부분의 삽질은 거기서 시작됩니다.
'AI활용' 카테고리의 다른 글
| Claude Code sandbox.credentials 설정, 기본값만 믿으면 안 되는 이유 (0) | 2026.07.11 |
|---|---|
| Claude Code Plan Mode 완벽 활용법: 설계부터 실행까지 (0) | 2026.07.05 |
| Claude Code Task Budgets, 왜 안 될까 — API 비용 폭주 진짜로 막는 법 (2026) (0) | 2026.07.05 |
| Claude Code ultrareview 써보니, 아무 커밋에나 쓸 건 아니었다 (0) | 2026.07.05 |
| AGENTS.md 완전 가이드: AI 코딩 도구 28개가 함께 읽는 단 하나의 파일 (1) | 2026.07.05 |