코르독 (KorDoc) 설치·사용법 — HWP·HWPX·PDF·XLSX·DOCX 등

Q: 코르독(KorDoc)은 무료인가요?

네, 코르독은 오픈소스 프로젝트로 GitHub에서 무료로 내려받을 수 있습니다. API 키도 필요하지 않습니다.

Q: npx 명령 실행 시 오류가 나면 어떻게 하나요?

Node.js 버전이 18 미만이거나 npm 캐시 문제일 수 있습니다. node -v로 버전을 확인하고 npm cache clean --force 후 재시도하세요.

Q: 변환된 마크다운 품질이 낮으면 어떻게 하나요?

HWP·HWPX 파일은 한컴 엔진 없이 구조를 파악하는 데 한계가 있을 수 있습니다. 복잡한 표나 그림이 많은 문서는 HWPX 형식으로 저장한 뒤 다시 시도해 보세요.

코르독(KorDoc) MCP 서버를 Claude Desktop 또는 Cursor에 연결하면 HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 AI가 직접 읽고 분석할 수 있습니다. API 키가 필요 없고 npx -y kordoc setup 한 줄로 설정이 끝납니다. 이 가이드에서는 설치부터 실제 사용까지 단계별로 안내합니다.

코르독(KorDoc)이 필요한 이유

한국의 공공기관·학교·기업은 HWP(한글) 형식 문서를 오랫동안 표준으로 사용해 왔습니다. 그 결과 계약서·보고서·공문·입찰서류 등 중요한 문서 대부분이 HWP 또는 HWPX 파일로 존재합니다. 문제는 Claude, ChatGPT 같은 AI가 이 형식을 기본적으로 읽지 못한다는 점입니다.

이를 해결하려면 HWP 파일을 AI가 이해할 수 있는 형식으로 변환해 주는 중간 다리가 필요합니다. 코르독(KorDoc)이 바로 그 역할을 합니다. MCP(Model Context Protocol) 규격을 따르기 때문에 Claude Desktop·Cursor 등 MCP 호환 클라이언트에 연결하는 것만으로 AI가 HWP·HWPX·PDF·XLSX·DOCX를 마크다운으로 변환해 이해할 수 있게 됩니다.

실제 활용 예시는 다양합니다. 공무원이 행정 공문을 Claude에 넣어 요약을 받거나, 법무 담당자가 계약서 초안(HWP)을 검토 요청하거나, 연구자가 보고서(PDF)에서 특정 수치를 추출하는 것 모두 가능합니다. API 키 발급이나 별도 서비스 가입 없이 로컬에서 처리하기 때문에 기밀 문서도 안심하고 사용할 수 있습니다.

사용자 요청
    │
    ▼
Claude Desktop / Cursor (MCP 클라이언트)
    │  MCP 프로토콜
    ▼
코르독 (KorDoc) MCP 서버
    │  파일 파싱 & 마크다운 변환
    ▼
HWP · HWPX · PDF · XLSX · DOCX 파일

코르독(KorDoc) 지원 형식

형식	확장자	주요 사용처
한글 문서	.hwp, .hwpx	공공기관, 학교, 법원 서류
PDF	.pdf	계약서, 보고서, 논문
엑셀	.xlsx	데이터표, 재무제표
워드	.docx	기업 문서, 제안서

API 키 없이 모든 형식을 로컬에서 처리하므로 민감한 공문서를 외부 서버에 올리지 않아도 됩니다.

준비물

Node.js 18 이상 — node -v로 버전 확인. macOS는 Homebrew(brew install node), Windows는 공식 설치 프로그램 사용을 권장합니다.
Claude Desktop 또는 MCP를 지원하는 편집기(Cursor, Continue, Zed 등). Claude Desktop은 claude.ai에서 무료로 내려받을 수 있습니다.
인터넷 연결 — 최초 패키지 내려받기 시에만 필요합니다. 이후 실행은 로컬에서 이루어집니다.
분석할 HWP·PDF·XLSX·DOCX 파일 — 로컬 경로에 접근 가능해야 합니다.

kordoc MCP 설치 방법 — 단계별 가이드

1단계: Node.js 설치 확인

터미널을 열고 아래 명령을 실행합니다.

node -v

v18.0.0 이상이 출력되면 준비 완료입니다. 그 미만이거나 명령을 찾지 못하면 nodejs.org에서 LTS 버전을 내려받아 설치하세요.

2단계: Claude Desktop 설정 파일 열기

Claude Desktop의 MCP 설정 파일은 운영 체제별로 아래 경로에 있습니다.

운영 체제	경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

파일이 없으면 새로 만들면 됩니다.

3단계: mcpServers 항목에 kordoc 추가

설정 파일을 열어 아래와 같이 mcpServers 항목을 추가하거나 기존 항목에 병합합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

이미 다른 MCP 서버가 설정되어 있다면 mcpServers 객체 안에 "kordoc" 항목만 추가하면 됩니다.

4단계: Claude Desktop 재시작

파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 실행합니다. 채팅 입력창 근처 도구 아이콘을 클릭했을 때 kordoc 항목이 보이면 연결에 성공한 것입니다.

5단계: HWP·PDF 파일 분석 요청

이제 Claude 채팅창에서 아래처럼 요청할 수 있습니다.

/Users/사용자명/Documents/계약서.hwp 파일을 요약해 줘.

또는 파일 경로를 대화에 붙여넣고 “이 문서의 핵심 내용을 정리해 줘”라고 입력하면 코르독이 자동으로 파일을 마크다운으로 변환해 Claude에 전달합니다.

Cursor에서 설정하는 법

Cursor도 MCP를 지원합니다. .cursor/mcp.json 파일에 같은 형식으로 추가하면 됩니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

Cursor를 재시작하면 채팅창에서 @kordoc로 호출할 수 있습니다.

흔한 오류와 해결법

증상	원인	해결
`command not found: npx`	Node.js 미설치 또는 PATH 미설정	nodejs.org에서 설치 후 터미널 재시작
kordoc가 도구 목록에 안 보임	JSON 문법 오류 또는 앱 미재시작	설정 파일 JSON 유효성 검사 후 재시작
파일을 찾을 수 없다는 오류	파일 경로 오타 또는 접근 권한 부재	절대 경로 사용, 파일 권한 확인
변환 결과가 깨짐	구버전 HWP 바이너리 형식	HWPX(XML 기반)로 다시 저장 후 재시도

서버	특징	지원 형식
코르독 (KorDoc)	PDF·XLSX·DOCX도 함께 처리, 단일 서버	HWP, HWPX, PDF, XLSX, DOCX
HWP-MCP	HWP·HWPX 읽기·편집·생성 특화	HWP, HWPX
한포지 (HwpForge)	HWPX 표준(KS X 6101) 기반 읽기·쓰기·변환	HWPX

자주 묻는 질문

코르독(KorDoc)은 무료인가요?

네, 코르독은 오픈소스 프로젝트입니다. GitHub 저장소에서 소스를 확인할 수 있으며 API 키도 별도로 발급받지 않아도 됩니다.

HWP 파일 외에 어떤 형식을 지원하나요?

공식 저장소 기준으로 HWP·HWPX·PDF·XLSX·DOCX 등 한국 공공기관과 기업에서 자주 쓰는 형식을 지원합니다. 최신 지원 형식은 GitHub 저장소의 README에서 확인하세요.

Claude Desktop 말고 Cursor에서도 쓸 수 있나요?

네, MCP 프로토콜을 지원하는 Cursor·Continue·Zed 등의 클라이언트에 동일한 방식으로 설정할 수 있습니다. 위의 “Cursor에서 설정하는 법” 항목을 참고하세요.

npx 명령 실행 시 오류가 나면 어떻게 하나요?

Node.js 버전이 18 미만이거나 npm 캐시 문제일 수 있습니다. node -v로 버전을 확인하고, 필요하면 npm cache clean --force 후 다시 시도해 보세요.

변환된 마크다운 품질이 낮으면 어떻게 하나요?

HWP·HWPX 파일은 한컴 독점 형식이라 구조 파악에 한계가 있을 수 있습니다. 복잡한 표나 그림이 많은 문서는 HWPX 형식으로 저장한 뒤 다시 시도해 보세요. 그래도 품질이 부족하면 HWPX 전용 서버인 한포지(HwpForge)를 병행해 사용하는 것도 방법입니다.

비슷한 MCP 서버와 차이점이 뭔가요?

코르독은 HWP뿐 아니라 PDF·XLSX·DOCX까지 단일 서버에서 처리한다는 점이 특징입니다. HWP 전용이 필요하다면 HWP-MCP나 한포지(HwpForge)를, 여러 형식을 한꺼번에 다뤄야 한다면 코르독을 선택하세요.

코르독 실전 활용 팁

설치를 마쳤다면 아래와 같은 방식으로 생산성을 높일 수 있습니다.

요약 요청: “이 공문서의 핵심 결정 사항 3가지를 요약해 줘”처럼 구체적으로 요청하면 마크다운 변환 후 즉시 답변이 옵니다.
비교 분석: 두 버전의 계약서(DOCX, HWP)를 차례로 불러와 “두 문서의 조항 차이를 표로 정리해 줘”라고 요청할 수 있습니다.
데이터 추출: XLSX 파일을 넣고 “2023년 매출 항목만 추려서 CSV 형태로 정리해 줘”라고 하면 Claude가 표 데이터를 파싱해 줍니다.
한영 번역: 영어권 파트너에게 제출할 문서가 HWP라면 코르독으로 마크다운 변환 후 “이 내용을 영어로 번역해 줘”라고 이어서 요청하면 됩니다.

HWP 단독 편집이 필요하다면 HWP-MCP 서버와 함께 사용하면 읽기·편집·생성을 모두 커버할 수 있습니다.

다음 단계

코르독을 설치했다면 실제 업무 문서를 불러와 요약·번역·데이터 추출 등을 시험해 보세요. 더 많은 한국어 MCP 서버는 MCP모아 서버 목록에서 확인하실 수 있으며, 개발도구 카테고리에서 관련 도구를 묶어서 보실 수도 있습니다. 직접 만든 MCP 서버가 있다면 서버 등록 페이지에 제출해 한국 개발자 커뮤니티와 공유해 보세요.