회사든 관공서든 문서를 주고받다 보면 한 번쯤은 이런 경험이 있습니다. ChatGPT나 Claude에게 보고서를 요약시키고 싶은데, 손에 있는 파일이 하필 HWP입니다. 열어서 전체 선택하고 복사해서 붙여넣었더니 표는 다 깨져 있고, 병합된 셀은 줄 맞춤이 엉망이고, 각주는 본문 한가운데 끼어 있습니다. 결국 정리하는 데 요약보다 더 많은 시간을 씁니다.
이 글은 그 번거로움을 통째로 없애 주는 오픈소스 도구 kordoc의 입문 가이드입니다. 총 5편으로 나눠 쓰는 시리즈의 첫 편이고, 전체 지도 역할을 하는 글이라 설치와 사용법을 맛보기로 모두 훑어 드립니다. 읽고 나면 kordoc이 무엇이고 내 업무에 쓸 만한지 판단이 서실 겁니다. 세부 실습은 뒤의 4편에서 하나씩 풀어 갑니다.
kordoc이 뭔가요, 한 줄로 정리하면
kordoc은 한국에서 쓰는 거의 모든 문서 형식을 마크다운과 구조화된 데이터로 바꿔 주는 도구입니다. 아래아한글 파일부터 PDF, 엑셀, 워드, 파워포인트, 심지어 이미지까지 받아 줍니다. 반대로 마크다운을 다시 한글 문서로 되돌리는 것까지 됩니다.
만든 사람은 공무원으로 7년간 문서 업무를 해온 개발자라고 합니다. 저장소 소개 문구도 “대한민국 문서지옥에서 7년 버틴 공무원이 만들었다”는 식으로 시작합니다. 실제로 기능 목록을 보면 일반적인 변환 도구가 놓치는 지점을 정확히 짚고 있습니다. 병합 셀이 복잡한 표, 선이 없는 PDF 표, 손상된 HWPX 파일 복구, 신구대조표 같은 것들입니다. 공문서를 만져 본 분이라면 고개가 끄덕여지는 목록입니다.
쓰는 방법도 세 가지입니다. 터미널에서 명령어로 쓰는 CLI, 코드에서 불러 쓰는 라이브러리, 그리고 Claude 같은 AI가 직접 문서 도구를 호출하게 만드는 MCP 서버입니다. 이 글에서는 세 가지를 모두 짧게 맛보겠습니다.
왜 HWP는 AI에게 그렇게 어려운 문서일까
kordoc이 왜 필요한지 이해하려면 HWP가 왜 까다로운지부터 알아야 합니다. PDF나 워드는 해외 도구가 워낙 많아서 텍스트를 뽑는 방법이 흔합니다. 하지만 HWP는 사실상 한국에서만 쓰이는 형식이라 외국 도구의 지원이 약합니다. 게다가 오래된 HWP 5.x는 일반 파일이 아니라 OLE2라는 복합 문서 구조로 되어 있어서, 안쪽을 열어 보지 않고는 글자 하나 꺼내기 어렵습니다.
HWPX는 상대적으로 열려 있는 형식이지만, 표 안에 표가 들어가거나 칸이 병합된 공문서 양식을 구조 그대로 읽으려면 별도의 해석이 필요합니다. 여기에 PDF 쪽 문제도 겹칩니다. 테두리가 없는 표는 눈으로는 표인데 파일 안에서는 그냥 글자 덩어리여서, 단순 추출을 하면 열 순서가 뒤섞입니다.
LLM이 문서를 제대로 이해하려면 글자만이 아니라 구조가 살아 있어야 합니다. 어느 줄이 제목이고, 어느 칸이 어느 항목의 값인지 알아야 하니까요. kordoc이 목표로 하는 것은 바로 이 구조 복원입니다.
kordoc이 읽을 수 있는 문서 포맷
지원 범위는 넓은 편입니다. 한글 쪽으로는 HWP 3.x와 5.x, HWPX, HWPML까지 받습니다. 1996년부터 2002년 무렵의 옛 HWP 3.x까지 포함이라는 점이 눈에 띕니다. 오피스 쪽으로는 PDF, 엑셀의 XLS와 XLSX, 워드의 DOCX, 파워포인트의 PPTX를 읽습니다. 마지막으로 PNG, JPG, WebP 같은 이미지도 내장 OCR로 읽어 냅니다.
처리 방식은 형식별로 다릅니다. 예를 들어 PDF는 읽기 순서를 계산해 2단 편집 문서도 순서대로 풀어내고, 엑셀은 시트 하나를 한 쪽으로 보며, 파워포인트는 슬라이드 하나를 한 쪽으로 봅니다. 열기 암호가 걸린 HWPX나 HWP도 비밀번호 옵션을 주면 읽을 수 있습니다. 한컴의 문서보안(DRM)이 걸린 파일만은 열 수 없다고 명시되어 있으니, 업무 문서를 다루실 때 이 점은 알아 두시는 게 좋습니다.
문서가 처리되는 5단계 흐름
위의 대표 이미지가 kordoc의 전체 흐름입니다. 말로 풀어 보면 이렇습니다.
첫 번째는 입력입니다. HWP, PDF, 이미지, 엑셀 같은 원본 파일을 넣습니다. 두 번째는 파싱과 OCR 단계입니다. 표와 수식까지 구조를 복원하고, 글자층이 없는 스캔본은 로컬 OCR이 읽습니다. 세 번째는 AI가 읽기 좋은 형태로의 변환입니다. 마크다운으로 바꾸거나, RAG에 쓰기 좋게 청크로 나눕니다. 네 번째는 AI 에이전트 연결입니다. MCP로 등록해 두면 Claude 같은 클라이언트가 이 기능을 도구처럼 호출합니다. 다섯 번째는 서식 보존 생성입니다. 편집한 내용을 원본 서식 그대로 한글 문서로 되돌립니다.
보통 문서 변환 도구는 두 번째나 세 번째에서 끝납니다. kordoc이 독특한 부분은 네 번째와 다섯 번째입니다. 읽는 데서 멈추지 않고 AI가 고친 결과를 다시 공문서 형태로 내보내는 왕복 구조를 갖췄다는 점입니다.
설치는 이렇게 시작합니다
필요한 것은 Node.js 하나입니다. 공식 문서에는 20 이상이라고 안내되어 있으니, 터미널에서 먼저 버전을 확인하세요.
node -v20 미만이면 Node.js를 올린 뒤 진행합니다. 그다음은 목적에 따라 갈립니다. 명령줄에서 한두 번 써보는 것이 목적이라면 설치조차 필요 없습니다. 아래처럼 npx로 바로 실행하면 됩니다.
npx kordoc 보고서.hwp내 프로젝트 코드에서 불러 쓰려면 일반 npm 패키지처럼 설치합니다.
npm install kordocPDF와 OCR에 필요한 의존 패키지는 기본으로 같이 설치됩니다. 용량을 줄이려고 선택 의존성을 빼면 PDF와 OCR 기능이 함께 빠지니 주의하세요. PDF를 인쇄용으로 렌더링하는 기능만 puppeteer-core를 따로 설치해야 합니다.
터미널에서 바로 써보기
처음 써보는 분께 가장 쉬운 시작은 CLI입니다. 파일 하나를 마크다운으로 바꿔 파일로 저장하는 명령은 이렇게 생겼습니다.
npx kordoc 보고서.hwp -o 보고서.md문서에 그림이 있으면 images 폴더가 따로 생기고 그 안에 이미지 파일이 저장됩니다. 폴더 안의 PDF를 한꺼번에 바꾸려면 별표 패턴과 출력 폴더 옵션을 씁니다.
npx kordoc *.pdf -d ./변환결과/특정 쪽만 필요하면 쪽 범위를 주고, 스캔본이면 OCR 옵션을 켭니다.
npx kordoc 보고서.hwpx --pages 1-3
npx kordoc 스캔본.pdf --ocr결과를 JSON으로 받고 싶을 때는 형식 옵션을 지정합니다. 이 JSON에는 본문 블록 구조와 메타데이터가 함께 담깁니다.
npx kordoc 검토서.hwpx --format json수신함 폴더를 계속 지켜보다가 파일이 떨어지면 자동으로 변환하는 감시 모드도 있어서, 문서가 계속 들어오는 업무라면 이 기능만으로도 쓸모가 큽니다.
npx kordoc watch ./수신함 -d ./변환결과CLI 옵션이 워낙 많아서 이 글에서는 가장 자주 쓰는 것만 뽑았습니다. 전체 옵션과 실패했을 때의 오류 코드 해석은 2편 kordoc CLI 사용법, npx 한 줄로 HWP를 마크다운으로 변환하는 법에서 따로 정리합니다.
코드에서 불러 쓰기
개발자라면 라이브러리로 쓰는 편이 자연스럽습니다. 사용법은 놀라울 정도로 간단합니다.
import { parse } from "kordoc"
import { readFileSync } from "fs"
const result = await parse(readFileSync("사업계획서.hwpx"))
if (result.success) {
console.log(result.markdown)
console.log(result.blocks)
}result.markdown은 LLM에 바로 넣을 수 있는 마크다운 문자열이고, result.blocks는 제목과 문단과 표를 구조 그대로 담은 배열입니다. 실패했을 때도 예외를 던지지 않고 success가 false인 결과 객체를 돌려주기 때문에, 대량 변환 코드에서 파일 하나가 깨졌다고 전체가 멈추는 일을 막기 좋습니다.
RAG를 만드는 분이라면 청크 변환을 눈여겨보세요. CLI에서 --format chunks 옵션을 주면 문서의 제목 위계를 경로 형태로 달아 둔 청크가 나오고, 표는 독립된 청크로 따로 빠집니다. 일반적인 글자 수 단위 자르기보다 검색 품질이 좋아지는 이유가 이 구조 정보에 있습니다. 스캔 PDF를 OCR로 읽는 방법과 함께 5편 kordoc RAG 청크 변환과 스캔 PDF OCR에서 자세히 다룹니다.
Claude 같은 AI에 붙이는 MCP 연동
kordoc이 많이 화제가 되는 이유가 바로 이 부분입니다. MCP는 AI 클라이언트가 외부 도구를 호출할 수 있게 해 주는 규격인데, kordoc은 MCP 서버를 내장하고 있어서 한 번 연결해 두면 대화창에서 “이 HWP 파일 요약해 줘”라고 말하는 것만으로 문서를 읽습니다.
연결은 설치 마법사 한 줄이면 끝납니다.
npx -y kordoc setup내 컴퓨터에 설치된 AI 클라이언트를 찾아서 보여 주고, 고른 곳의 설정 파일에 자동으로 등록해 줍니다. 대상은 Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Zed, Codex 같은 곳들입니다. 등록 후 해당 프로그램을 다시 시작하면 문서 도구 스무 개 남짓이 활성화됩니다.
마법사를 쓰지 않고 직접 설정 파일을 고치고 싶다면 아래 내용을 MCP 서버 설정에 넣습니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}Claude Code를 쓰신다면 플러그인 방식도 있습니다. 마켓플레이스를 추가하고 설치하면, HWP 파일을 언급하거나 공문서 작성을 요청할 때 kordoc 스킬이 알아서 켜집니다.
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc운영체제별 설정 파일 위치와 Windows에서 흔히 만나는 실행 오류 해결법은 3편 kordoc Claude Desktop 연결 방법, MCP 설정부터 Claude Code·Cowork 플러그인까지에서 화면과 함께 따라 하도록 정리합니다.
읽기만 하는 게 아니라 쓰기도 합니다
kordoc을 단순한 변환기로 보면 절반만 본 것입니다. 쓰기 쪽 기능이 실무에서는 더 반갑습니다.
가장 먼저 눈에 띄는 것은 양식 채우기입니다. 신청서 같은 HWPX 양식에 성명과 주소를 값으로 넘기면 글꼴과 정렬을 그대로 유지한 채 칸을 채워 줍니다. 채우기 전에 어느 값이 어느 칸에 들어갈지 미리 확인하는 모드도 있어서, 엉뚱한 칸에 들어가는 사고를 줄일 수 있습니다. 표준 기안문 서식도 패키지에 내장되어 있어서 이름만 지정하면 공문서 틀이 나옵니다.
다음은 마크다운에서 HWPX로의 변환입니다. AI가 써 준 보고서 초안을 마크다운으로 받아서, 보고서나 계획서 같은 공문서 프리셋을 지정해 한글 문서로 뽑는 방식입니다. 항목 부호와 여백, 글꼴을 공문서 관행에 맞춰 자동으로 입혀 줍니다.
기존 문서를 고치는 서식 보존 편집도 있습니다. 원본을 마크다운으로 뽑아 고친 뒤 패치 명령으로 원본에 반영하면, 손대지 않은 부분의 서식은 그대로 남습니다. 두 문서를 비교해 신구대조표를 만들어 주는 기능과, 주민등록번호 같은 개인정보를 찾아 가려 주는 마스킹 기능도 같은 계열입니다. 마스킹은 공개 전에 사람이 최종 확인해야 하고, 이미지 속 글자는 자동 탐지 범위에 들어가지 않는다고 문서에 분명히 적혀 있으니 이 점은 꼭 기억하세요.
이 쓰기 기능들은 4편 kordoc으로 HWPX 양식 자동 작성하기에서 실제 예제 파일로 돌려 봅니다.
폐쇄망과 보안, 회사에서 쓸 때 알아둘 점
업무 문서를 다룬다면 보안이 가장 먼저 궁금하실 겁니다. kordoc의 OCR은 외부 API를 쓰지 않고 내 컴퓨터의 CPU에서 로컬로 돌아갑니다. 한국어 인식 모델은 첫 사용 때 약 18MB를 내려받는데, 이후에는 내려받은 모델로 동작합니다. 외부 통신을 아예 막고 싶다면 KORDOC_OFFLINE=1 환경 변수로 모든 외부 통신을 차단할 수 있고, MCP가 접근할 수 있는 파일 범위도 KORDOC_ROOT로 특정 폴더 안으로 제한할 수 있습니다.
폐쇄망 환경이라면 모델 파일을 미리 내보내서 옮겨 심는 방법과 오프라인 설치 번들이 문서에 안내되어 있습니다. ZIP 폭탄이나 경로 조작 같은 공격을 막는 방어 로직도 들어 있다고 합니다. 다만 도구가 안전하다는 말과 우리 회사 보안 규정에서 허용된다는 말은 다른 이야기이니, 사내 문서에 적용하기 전에는 반드시 보안 담당 부서의 기준을 먼저 확인하세요.
GitHub와 npm, 어디를 봐야 할까
kordoc을 검색하면 주소가 두 개 나와서 헷갈릴 수 있습니다. GitHub 저장소는 소스코드 원본과 이슈, 개선 이력이 있는 개발의 본거지입니다. npm 페이지는 그 소스를 빌드해 배포한 패키지가 올라가는 설치용 창구입니다. npm install이나 npx로 받는 것은 npm에 올라온 배포본입니다.
두 곳이 완전히 다른 코드는 아니지만, 저장소에 반영된 최신 변경이 아직 npm 배포 버전에 들어오지 않은 시간 차이는 있을 수 있습니다. 사용법과 버그 제보, 최신 변경 확인은 GitHub에서 하고, 설치하려는 버전 번호는 npm에서 확인하는 식으로 나눠 보시면 편합니다.
마무리, 이 시리즈를 이렇게 따라가 보세요
정리하면 kordoc은 한국 문서 환경의 가장 까다로운 문제인 HWP와 공문서 표를 AI가 읽고 쓸 수 있는 형태로 바꿔 주는 도구입니다. 읽기에서 끝나지 않고 양식 채우기와 HWPX 생성, 서식 보존 편집까지 이어지는 왕복 구조가 가장 큰 특징이고, CLI와 라이브러리와 MCP라는 세 가지 입구가 있어서 개발자가 아니어도 시작할 수 있습니다.
처음이라면 이 순서를 권합니다. 먼저 npx kordoc 파일명 한 줄로 내가 가진 문서를 하나 변환해 보세요. 결과가 마음에 들면 2편에서 옵션을 익히고, Claude에 연결하고 싶어지면 3편으로, 업무 자동화가 목표라면 4편으로, RAG나 스캔 문서가 목표라면 5편으로 가시면 됩니다.
문서 변환에 쓰던 반나절의 수작업이 명령어 한 줄로 줄어드는 경험은 직접 해 보셔야 실감이 납니다. 가진 HWP 파일 하나로 지금 시작해 보세요.