목차(클릭하세요)
hwp/hwpx/pdf 모두 파싱해주는 교사/공무원에게 꼭 필요한 맥가이버칼(God!)
1.
[설치]MCP 서버사용을 위한 설치
2.
[사용1]누구나_AI에이전트(Claude Desktop를 기준으로) + Antigravity, vsc등 모두 가능
3.
[사용2]중수_CLI 활용(별로 추천 안함)
•
아래 명령어 실행시 오류가 없다면 ‘사용1’권장
#강력추천의 이유
우리가 겪는 문제들•
학교 공문, 교육과정, 지침서 
높은 확률로 .hwp/.hwpx 또는 pdf
높은 확률로 .hwp/.hwpx 또는 pdf•
Claude한테 “이 공문 요약해줘”를 하려면 Claude가 내용을 읽을 수 있어야 하는데
•
인식률이 좋지 않아.. PDF로 변환해서 붙여넣거나, 직접 복사-붙여넣기를 했거나
•
아니면 이미지로 변환해서 넣거나...
kordoc는 그 문제를 해결함.•
HWP/HWPX/PDF → Markdown 자동 변환. 한컴 설치도 필요 없고, Windows 전용도 아님.
•
순수 JavaScript로 만들어진 크로스플랫폼 parser이고, 실제 지방공무원이 7년간 관공서 문서와 싸우다 만든 검증된 도구임
[실제 페이지]광진구 류승인 주무관 운영
1. 설치_MCP 서버 사용을 위한 설치
1-1. 사전 조건
•
Node.js 18 이상이 반드시 설치되어 있어야 함
•
윈도우에서 터미널(cmd 또는 powershell)을 실행하여 확인
node -v # v18.0.0 이상인지 확인
npm -v
Bash
복사
•
Node.js가 없다면 아래그림처럼 빨간색 경고메시지 출력
•
•
Windows 설치 프로그램 (.msi) 클릭
•
파워셀이 실행되면서 관련 라이브러리도 설치해주는듯
•
npm설정에서 오류가 발생했다면?
◦
해결법 : PowerShell을 관리자 권한으로 열고, 다음 명령어 입력
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Bash
복사
1-2. 자동 설치 (추천)
수동설치 하는 방법도 있긴하지만, 초보자인 경우 자동설치 추천!•
터미널에서 아래 한 줄만 실행
npx -y kordoc setup
Bash
복사
•
대화형 마법사가 실행되면서:
1.
설치된 AI 클라이언트 자동 감지 ([감지됨] 표시)
2.
선택한 클라이언트 설정 파일 자동 패치
3.
클라이언트 재시작 후 8개 도구 즉시 활성화
•
지원 클라이언트: Claude Desktop / Cursor / Claude Code / VS Code / Windsurf / Gemini CLI / Zed / Antigravity
Windows에서는 cmd /c npx 래핑도 자동 처리됨. 수동 JSON 편집 불필요.
•
설치가 되었는지 확인하기
◦
해당 주소로 접속:C:\Users\사용자명\AppData\Roaming\Claude
◦
claude_desktop_config.json 파일을 열어서 확인해보기
•
클로드 데스크탑을 실행한뒤 ‘커넥터’에 가보면 kordoc 설치를 확인할 수 있음
•
자동설치가 완료되었다면 2번파트로 이동
1-3. 수동 설치 (config 직접 편집할 경우)
claude_desktop_config.json을 직접 편집하는 경우:
macOS / Linux:
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
JSON
복사
Windows (Claude Desktop이 .cmd를 못 찾을 때):
{
"mcpServers": {
"kordoc": {
"command": "cmd",
"args": ["/c", "npx", "-y", "kordoc", "mcp"]
}
}
}
JSON
복사
흔한 실수: "args": ["-y", "kordoc-mcp"] 처럼 패키지명을 kordoc-mcp로 쓰면 npm에 없는 패키지라 실패함. 반드시 "kordoc", "mcp" 두 개로 분리할 것1-4. 활성화되는 MCP 도구 8개
•
가장 많이 사용되는 것은 parse_document
도구 | 설명 |
parse_document | HWP/HWPX/PDF/XLSX/DOCX → Markdown |
detect_format | 매직 바이트로 포맷 자동 감지 |
parse_metadata | 메타데이터만 빠르게 추출 |
parse_pages | 특정 페이지 범위만 파싱 |
parse_table | N번째 테이블만 추출 |
compare_documents | 두 문서 비교 (크로스 포맷 지원) |
parse_form | 양식 필드를 JSON으로 추출 |
fill_form | 양식 템플릿에 값 채우기 (HWPX 서식 보존) |
1-5. 트러블슈팅
•
트러블 슈팅이란? 문제가 생겼을 때 원인을 찾아 해결하는 과정
문제가 생겼을 때 원인을 찾아 해결하는 과정1.
MODULE_NOT_FOUND 또는 Cannot find module ...\dist\cli.js 오류:
npm uninstall -g kordoc
npx -y kordoc@latest setup
Bash
복사
2.
Windows PowerShell에서 PSSecurityException 오류:
PowerShell 기본 보안 정책이 서명 없는 .ps1을 차단하는 것으로 kordoc 자체 문제는 아님
방법 1 — cmd 창에서 실행 (가장 안전):
윈도우 키 → cmd 검색 → Enter
npx -y kordoc setup
Plain Text
복사
방법 2 — PowerShell 실행 정책 완화 (관리자 권한 필요):
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# 이후 PowerShell 재시작 → npx -y kordoc setup
PowerShell
복사
2. 사용방법: AI 에이전트로 사용하기 (Claude Desktop 기준)
•
설치만 완료되면 터미널 없이 Claude 데스크탑의 채팅창에서 바로 사용 가능함
주의: 이건 웹페이지의 클로드에서 실행되지 않음, 무조건 로컬 컴퓨터에 설치된 클로드, 즉 클로드 데스크탑에서 실행해야 함!이유?
kordoc은 Node.js 기반 프로그램이라, 실행 자체가 내 컴퓨터의 Node.js 환경에서 이루어짐.
웹 브라우저는 Node.js를 직접 실행할 수 없기 때문에, 클라우드 서버에서 돌아가는 웹버전 Claude(claude.ai)에서는 kordoc을 호출할 방법이 없음.
왜 Node.js를 써야하는가?•
Node.js는 "자바스크립트를 브라우저 밖에서 실행할 수 있게 해주는 프로그램
•
원래 자바스크립트는 크롬 같은 브라우저 안에서만 실행됐음. Node.js가 등장하면서 내 컴퓨터(로컬)에서도 직접 실행할 수 있게 됨.
[정리]
•
kordoc도 자바스크립트(TypeScript)로 만들어진 프로그램이라, Node.js가 깔려 있어야 내 컴퓨터에서 실행 가능
[예외] 만약 클로드 사용자라면 SKILL을 알고 있을 것이고, HWPX관련 스킬이 설치되어있다면, kordoc MCP를 사용할 것인지, hwpx SKILL을 사용할 것인지 미리 알려줘야 함
•
SKILL.md 자체가 토큰 소모 하므로 kordoc MCP 사용 권장
2-1. 기본 사용 흐름
파일을 Claude Desktop에 첨부 또는 파일 경로 전달
↓
Claude가 kordoc 도구를 자동으로 호출해서 파싱
↓
결과를 채팅창에서 바로 확인
Plain Text
복사
2-2. 사용 예시 프롬프트
문서 읽기이 HWPX 파일을 읽고 핵심 내용을 요약해줘.kordoc MCP사용
Plain Text
복사
[프롬프트 사용예시와 결과]
•
사용예시
•
사용결과
첨부된 5개의 파일을 parse_document로 읽고 표 부분만 정리해서 hwpx파일로 만들어
Plain Text
복사
•
특히 놀라운점은 5개의 파일을 업로드할때, 일부러 중복된 파일을 만들어 각각 hwp, hwpx로 만들어 중복작업을 하는지 체크했는데, 함정카드를 잘 피해감
문서 비교•
특히, 과거에 주로 사용했던 hwp와 최근 권장 사용중인 hwpx가 모두 입력으로 들어갔을때 과연, 오류없이 잘 작동되는가?
다음 2개의 파일은 25년도 계획서와 26년 계획서야
compare_documents로 비교해서 변경사항을 표로 정리해줘.
Plain Text
복사
•
내 의도를 정확히 파악하고 한치의 오차없이 비교분석.. 놀랍습니다.
2-3. 사용상의 꿀팁
MCP 도구 사용 시 상대 경로보다 절대 경로를 쓰면 경로 오류를 줄일 수 있음•
“C:\Users\이름\Documents\보고서.hwpx 파일” 
이런형태로 절대경로 사용시 오류발생률이 더 줄어듦
이런형태로 절대경로 사용시 오류발생률이 더 줄어듦
2-4. 지원 포맷 정리
포맷 | 주요 특징 |
HWPX (한컴 2020+) | 중첩 테이블, 병합 셀, 손상 ZIP 복구 |
HWP 5.x (레거시) | 배포용 복호화, 각주/하이퍼링크, 이미지 추출 |
HWPML (XML 기반 HWP) | XML 시그니처 자동 감지 |
PDF | 선 기반 테이블 감지, 2단 레이아웃, OCR 연동 가능 |
XLSX | 병합 셀, 다중 시트, 수식 표시 |
DOCX | 스타일 heading, 번호 매기기, 이미지 추출 |
DRM 걸린 배포용 HWPX는 Windows + 한컴오피스 설치 환경에서만 자동 추출 가능3. 사용방법: 구글 안티그래비티로 사용하기
•
클로드 토큰 소모 없이 안티그래비티에서 MCP로 활용하기
처음 설치과정에서 안티그래비티 환경도 체크하였다면1.
설치된 AI 클라이언트 자동 감지 ([감지됨] 표시)
2.
선택한 클라이언트 설정 파일 자동 패치
3.
클라이언트 재시작 후 8개 도구 즉시 활성화
•
지원 클라이언트: Claude Desktop / Cursor / Claude Code / VS Code / Windsurf / Gemini CLI / Zed / Antigravity
Windows에서는 cmd /c npx 래핑도 자동 처리됨. 수동 JSON 편집 불필요.
•
설치가 되었는지 확인하기
◦
안티그래비티에서 MCP Servers를 실행하거나
◦
아니면 직접, mcp_config.json파일을 확인
[사용방법]동일하게 해당 폴더에 한글파일들을 준비한뒤 시작
•
안티그래비티의 결과
◦
클로드 데스트탑과 비교했을때. 뭔가 미묘한 차이가 있는듯..
◦
아마도 사용된 LLM모델이 달라져서인듯
•
참고로 안티그래비티는 사용할 LLM모델을 선택할 수 있음
4. 사용2_중수: CLI 터미널 직접 활용
별도 설치 없이 npx kordoc 파일명 만으로 바로 실행 가능. Node.js만 있으면 됨.
•
이 방식의 장점은 무료사용자도 가능, 안티그래비티나 클로드 데스크탑을 따로 설치하지 않아도 된다는 장점이 있음
Node.js만 설치되어 있다면, 바로 터미널 창에서 작업 가능3-1. 기본 파싱
#사용법 예시
# 터미널에 결과 출력
npx kordoc 사업계획서.hwpx
# 마크다운 파일로 저장
npx kordoc 보고서.hwp -o 보고서.md
# 여러 파일 일괄 변환 (결과 폴더 지정)
npx kordoc *.pdf -d ./변환결과/
# JSON 형식 출력 (blocks + metadata 포함)
npx kordoc 검토서.hwpx --format json
# 특정 페이지 범위만 파싱
npx kordoc 보고서.hwpx --pages 1-3
Bash
복사
[실제 사용] 터미널 창에서 해당 명령어를 입력하면 됨
3-2. 양식 채우기
# 직접 값 입력
npx kordoc fill 신청서.hwpx -f '성명=홍길동, 주소=서울' -o 결과.hwpx
# JSON 파일로 값 입력
npx kordoc fill 신청서.hwpx -j values.json -o 결과.hwpx
# 채울 필드 목록만 미리 확인 (dry-run)
npx kordoc fill 신청서.hwpx --dry-run
Bash
복사
values.json 예시:{
"성명": "홍길동",
"소속": "순수고등학교",
"직급": "교사",
"연락처": "010-0000-0000"
}
JSON
복사
3-3. 폴더 감시 (Watch) 모드
# 특정 폴더에 파일이 들어오면 자동 변환
npx kordoc watch ./수신함 -d ./변환결과
# 변환 완료 시 웹훅으로 알림
npx kordoc watch ./문서 --webhook https://api/hook
Bash
복사
활용 팁: 수신함 폴더를 Google Drive나 NAS와 연동하면 파일 저장만 해도 자동으로 Markdown 변환됨5. 마치며(사용후기)
•
kordoc은 읽기 전용 파서
•
표 테두리의 색상, 두께를 변환하는 등의 추가적인 기능은 불가
◦
kordoc 도구 자체가 직접적으로 표의 스타일(테두리 굵기 등)을 변경하는 기능은 지원하지 않기 때문
•
수합된 대량의 hwp, hwpx에서 특정 파일만 추출한다면 엄청난 효율성으로 사용가능!
5-1. kordoc의 역할과 한계
•
kordoc MCP가 훌륭한 **'눈(Read)'**이 되어 복잡한 한글 데이터를 정확히 parser(=추출)함
•
실제 문서작성을 위해 추가로 한글관련 파이썬 라이브러리가 설치되고 실행될 수 있음