한글(HWP) 파일을 Claude Code에 던져본 적 있다면 결과를 아실 겁니다. 못 읽습니다. PDF는 읽긴 하는데, 스캔본이면 글자를 못 꺼내고, 표는 자주 깨지고, 페이지 단위로 통째로 넣다 보니 토큰도 많이 먹습니다. 한국에서 일하는 이상 HWP와 PDF는 피할 수 없는데 말이죠.
해결은 단순합니다. 문서를 모델에게 직접 주지 말고, 마크다운으로 바꿔서 주는 것. 이 글은 그 변환을 맡는 kordoc MCP를 연결하고, 실제 문서를 변환해서 결과까지 확인한 기록입니다.
왜 마크다운인가
모델 입장에서 문서 포맷은 셋으로 갈립니다.
| 입력 형태 | 모델이 받는 것 | 문제 |
|---|---|---|
| HWP/HWPX | 읽기 불가 | 바이너리 포맷. 시작조차 안 됨 |
| PDF 원본 | 페이지 이미지+텍스트 | 토큰 비쌈, 표 깨짐, 스캔본은 부정확 |
| 마크다운 | 구조화된 텍스트 | 없음 — 제목·표·목록이 그대로 전달 |
같은 내용이라도 마크다운으로 주면 토큰은 줄고 구조는 살아납니다. 표가 표로, 제목 위계가 위계로 들어가니까 “3번 표에서 2차 대상 부서만 뽑아줘” 같은 요청이 정확해집니다.
연결 — 명령어 한 줄
kordoc은 npm 패키지라 설치랄 게 따로 없습니다. Claude Code에 MCP 서버로 등록하면 끝입니다.
claude mcp add kordoc -- npx -y kordoc mcp
등록하면 세션 안에서 문서 변환 도구들이 열립니다. 핵심은 네 가지입니다.
- parse_document — HWP3~5, HWPX, PDF, XLSX, DOCX, 이미지를 마크다운으로
- parse_table — 문서에서 N번째 표만 뽑기
- detect_format — 확장자가 아니라 실제 바이트로 포맷 판별
- generate_document — 반대 방향. 마크다운을 공문서 서식의 HWPX로
실전 — 공문서 하나를 왕복시켜 봤다
실제 업무 문서를 블로그에 올릴 수는 없으니, kordoc의 역방향 기능으로 개조식 보고서 샘플을 먼저 만들고 그걸 다시 마크다운으로 변환하는 왕복 시험을 했습니다. 생성된 HWPX는 115.5KB — 표지, 목차, 로마숫자 장 번호, □○※ 항목 부호까지 실제 정부 서식 그대로입니다.
이 파일을 parse_document에 넣으면 이렇게 돌아옵니다. (실제 출력 그대로입니다)
[포맷: HWPX]
📑 문서 구조:
- 사내 AI 도구 도입 추진 계획
- 추진 배경
- 추진 계획
- 기대 효과
## 추진 계획
□ 부서별 단계 도입
| 단계 | 대상 부서 | 기간 | 비고 |
| --- | --- | --- | --- |
| 1차 | 기획팀 | 2026. 8. | 시범 운영 |
| 2차 | 총무팀, 인사팀 | 2026. 9. | 확대 적용 |
| 3차 | 전 부서 | 2026. 10. | 전면 도입 |
눈여겨볼 것 세 가지.
- 문서 구조 요약이 먼저 나옵니다. 긴 문서라도 모델이 전체 뼈대를 먼저 잡고 본문을 읽습니다.
- 표가 마크다운 표로 살아서 나옵니다. PDF에서 자주 깨지는 부분이 여기인데, HWPX의 표 구조를 직접 읽으니 셀이 안 섞입니다.
- 항목 부호(□○※)가 유지됩니다. 개조식 문서의 위계가 그대로 전달됩니다.
표만 필요하면 문서 전체를 넣을 이유도 없습니다.
parse_table(file_path, table_index=0)
→ | 단계 | 대상 부서 | 기간 | 비고 | ...
100페이지 보고서에서 예산 표 하나만 뽑아 넣는 식으로 쓰면, 컨텍스트에는 딱 필요한 것만 들어갑니다. CLAUDE.md 세팅 가이드에서 말한 원칙 — 전부 미리 넣지 말고 필요한 것만 — 이 문서에도 그대로 적용되는 거죠.
스캔본은 OCR 옵션으로
옛날 문서 중엔 스캔해서 만든 이미지 PDF가 많습니다. 텍스트 층이 없어서 그냥 넣으면 글자를 제대로 못 꺼내는데, kordoc은 ocr 옵션을 켜면 내장 OCR(PP-OCRv5 한국어 모델)로 글자를 꺼냅니다. 정상 페이지는 그대로 두고 텍스트가 없는 페이지만 골라 인식하는 방식이라, 섞인 문서도 한 번에 처리됩니다. 변환 결과에 NEEDS_OCR 경고가 보이면 이 옵션으로 재시도하면 됩니다.
어디에 쓰면 좋은가
- 회의록·공문 아카이브를 지식베이스로 — 부서에 쌓인 HWP 뭉치를 일괄 변환해두면, 이후 세션에서 “작년 3분기 회의에서 이거 결정된 적 있어?” 같은 질문이 가능해집니다
- 표 데이터 추출 — 엑셀로 안 주고 HWP 표로 주는 자료,
parse_table로 바로 구조화 - 역방향 활용 — 모델이 쓴 초안을
generate_document로 공문서 서식 HWPX로 뽑아 제출용으로
정리
- HWP는 모델이 못 읽고, PDF는 비싸고 잘 깨진다 — 문서는 마크다운으로 바꿔서 준다
- 연결은
claude mcp add kordoc -- npx -y kordoc mcp한 줄 - 표만 필요하면
parse_table로 표만 — 컨텍스트에는 필요한 것만 넣는다 - 스캔본은
ocr옵션 — 텍스트 없는 페이지만 골라 인식한다 - 반대 방향(마크다운 → 공문서 HWPX)도 된다 — 초안 작성까지 이어진다
다음 글부터는 이 블로그를 만든 과정 자체를 시리즈로 다룹니다 — 왜 티스토리가 아니라 워드프레스 + Cloudflare Pages였는지부터.
