터미널에서 npx kordoc 파일명을 치는 것도 충분히 편합니다. 그런데 이런 생각이 들었습니다. 어차피 변환한 마크다운을 Claude에게 읽힐 거라면, 처음부터 Claude에게 “이 HWP 파일 요약해 줘”라고 말하면 안 될까요?
됩니다!! 그 연결 고리가 MCP입니다. 이 글은 kordoc 입문 시리즈 3편이고, kordoc을 Claude에 붙이는 방법만 따로 떼어 정리했습니다. kordoc이 무엇인지부터 궁금하시면 필라글인 kordoc 설치부터 사용법까지, HWP·PDF를 AI가 읽게 만드는 MCP 완전 가이드를 먼저 보시고, 명령어 사용법은 2편 kordoc CLI 사용법, npx 한 줄로 HWP를 마크다운으로 변환하는 법에 있습니다.
MCP는 한 줄로 이렇게 이해하면 됩니다
MCP는 AI 프로그램이 외부 도구를 호출할 수 있게 해 주는 연결 규격입니다. USB 단자 같은 것이라고 생각하시면 쉽습니다. Claude Desktop 쪽에 단자가 있고, kordoc이 그 단자에 꽂히는 문서 처리 장치입니다. 꽂아 두면 Claude가 필요할 때 알아서 kordoc을 불러서 HWP를 읽고, 표를 뽑고, 문서를 비교합니다.
사람이 할 일은 딱 한 번, 연결을 등록하는 것입니다. 그 뒤로는 대화창에서 말로 시키면 됩니다.
연결 전에 준비할 것
필요한 것은 Node.js와 Claude Desktop 앱입니다. kordoc은 npx로 실행되기 때문에 Node.js가 없으면 시작조차 되지 않습니다. 저는 설치 전에 npm 레지스트리에서 정보를 먼저 확인해 봤는데, 지금 배포된 최신 버전은 4.24.43이고 요구하는 Node.js 버전은 20 이상이었습니다. 필라글에서 20 이상을 기준으로 안내한 것과 같습니다.
터미널에서 버전부터 확인하세요.
node -v20보다 낮으면 Node.js부터 올립니다. 이 단계에서 가장 흔한 실수가 낮은 버전을 그대로 두고 연결하는 것인데, 그러면 Claude 쪽에서는 서버가 실행되지 않는다는 말만 나와서 원인을 찾기 어렵습니다.
방법 1, 설치 마법사로 30초 만에 끝내기
가장 쉬운 방법은 kordoc이 제공하는 설치 마법사입니다. 터미널에 이 한 줄을 치면 됩니다.
npx -y kordoc setup이 명령은 내 컴퓨터에 설치된 AI 클라이언트를 찾아 보여 주고, 고른 곳의 설정 파일에 kordoc 서버를 자동으로 넣어 줍니다. 공식 문서에 나온 대상은 Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Zed, Codex 등입니다. setup --help로 확인해 보면 맥, 윈도우, 리눅스에서 모두 동작하는 대화형 마법사라고 나옵니다.
목록에서 Claude Desktop을 고르고 끝나면, Claude Desktop을 완전히 종료했다가 다시 실행하세요. 창만 닫는 것으로는 부족하고, 메뉴나 트레이에서 앱 자체를 끝내야 새 설정을 읽습니다. 이걸 놓치고 “등록했는데 왜 안 보이지” 하며 한참 헤매는 분이 많습니다.
방법 2, 설정 파일을 직접 고치는 방법
마법사가 마음에 안 들거나 이미 다른 MCP 서버를 여러 개 쓰고 있어서 설정 파일을 직접 관리하고 싶다면 수동 등록이 낫습니다. Claude Desktop에서 상단 메뉴의 Claude, 설정, 개발자 항목으로 들어가 구성 편집 버튼을 누르면 설정 파일이 들어 있는 폴더가 열립니다. 운영체제마다 파일 위치가 다르기 때문에, 직접 경로를 찾기보다 이 버튼으로 여는 쪽이 안전합니다.
열린 폴더에서 claude_desktop_config.json 파일을 편집기로 엽니다. kordoc 공식 문서에 나온 등록 내용은 이렇습니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}여기서 주의할 점이 하나 있습니다. 파일에 이미 mcpServers 항목이 있다면 통째로 붙여 넣으면 안 되고, 기존 항목 안에 "kordoc": { ... } 블록만 추가해야 합니다. 이때 앞 항목 끝에 쉼표를 빠뜨리거나 마지막 항목 뒤에 쉼표를 남기면 JSON 문법 오류가 나서 Claude Desktop이 설정 파일 전체를 못 읽습니다. 저장하기 전에 괄호와 쉼표를 한 번 더 확인하세요.
윈도우에서 Claude Desktop이 npx.cmd를 찾지 못하는 경우가 있다고 kordoc 문서에도 안내되어 있습니다. 이때는 실행 명령을 cmd로 바꾸고 인자 앞에 /c와 npx를 붙입니다.
{
"mcpServers": {
"kordoc": {
"command": "cmd",
"args": ["/c", "npx", "-y", "kordoc", "mcp"]
}
}
}제대로 붙었는지 확인하는 법
저장하고 Claude Desktop을 재시작한 뒤 새 대화를 열어 보세요. 입력창 근처의 도구 표시에서 kordoc이 보이면 연결된 것입니다. 보이지 않는다면 다음 확인을 해 보세요.
저는 연결 문제를 구분하려고 kordoc 서버가 스스로 정상인지부터 따로 확인해 봤습니다. MCP 서버는 Claude 없이도 직접 띄워서 말을 걸어 볼 수 있습니다. 표준 입출력으로 초기화 요청과 도구 목록 요청을 보내 봤더니, 서버 이름은 kordoc, 버전은 4.24.43으로 응답했고 등록된 도구는 22개였습니다. 인터넷에 있는 예전 소개글에는 15개라고 적혀 있는데, 버전이 올라가면서 도구가 늘어난 것으로 보입니다. 시리즈 필라글에서 “스무 개 남짓”이라고 쓴 이유가 이것입니다.
도구 이름을 보면 용도가 짐작됩니다. 문서를 읽는 쪽은 parse_document, parse_pages, parse_table, parse_chunks, parse_metadata, detect_format이 있습니다. 비교와 양식 쪽은 compare_documents, parse_form, fill_form이 있고, 편집과 생성 쪽은 patch_document, generate_document, convert_to_hwpx가 있습니다. 그 밖에 개인정보를 가리는 redact_document, 문서를 그림으로 그려 보는 render_document, 공문서 표기법을 검사하는 lint_document, 도장을 찍는 place_seal 등이 있습니다.
그러니 Claude에게 직접 물어보는 것도 확인 방법입니다. 새 대화에서 “kordoc으로 쓸 수 있는 도구 목록을 알려 줘”라고 해 보세요. 22개 안팎의 이름이 나오면 성공입니다.
연결이 안 될 때 가장 먼저 의심할 곳은 세 군데입니다. Node.js 버전이 20 미만인지, 설정 파일에 JSON 문법 오류가 있는지, 앱을 완전히 종료했다가 켰는지입니다. 이 셋만 확인해도 대부분 해결됩니다.
이제 Claude에게 문서를 읽혀 보기
연결이 끝났으니 실제로 써 볼 차례입니다. 한 가지 알아 둘 점은, MCP 도구는 내 컴퓨터에 있는 파일의 경로를 받아서 일한다는 것입니다. 저는 parse_document 도구에 file_path라는 인자로 경로를 넘겨 호출해 봤는데, 대화창에 파일을 끌어다 놓는 것과는 방식이 다릅니다. 그러니 Claude에게 시킬 때는 파일의 전체 경로를 말해 주는 게 확실합니다.
테스트용으로 마크다운에서 HWPX 샘플을 하나 만들었습니다. 제목과 두 개의 소제목, 그리고 예산 표가 들어 있는 짧은 보고서입니다. 이 파일의 경로를 넘겨 parse_document를 호출했더니 가장 먼저 포맷과 쪽 수, 그리고 문서 구조 요약이 돌아왔습니다. 제목 밑에 추진 배경과 예산 내역이 계층으로 나열되어 있었고, 그 뒤에 본문 마크다운이 이어졌습니다. 표는 마크다운 표로 복원되었고, 개발비 1억 2천만 원이라는 숫자와 비고 칸까지 그대로였습니다.
이 구조 요약이 의외로 실용적입니다. 긴 문서를 읽을 때 Claude가 전체를 읽기 전에 목차를 먼저 파악하고, 필요한 쪽만 다시 불러올 수 있기 때문입니다.
실제로는 이렇게 말하면 됩니다.
/Users/내이름/Documents/2026_사업계획서.hwpx 파일을 kordoc으로 읽고 핵심 내용을 열 줄로 요약해 줘.이 두 문서를 kordoc으로 비교해서 달라진 조항만 알려 줘.
구버전: /Users/내이름/Documents/규정_구.hwp
신버전: /Users/내이름/Documents/규정_신.hwpx/Users/내이름/Documents/신청서.pdf 에서 3쪽에 있는 표만 뽑아서 보여 줘.두 번째 예시처럼 HWP와 HWPX를 섞어서 비교해도 됩니다. 형식이 달라도 비교가 된다고 공식 문서에 나와 있습니다. 세 번째는 parse_table 도구를 쓰는 요청이고, 큰 PDF에서 필요한 표 하나만 꺼낼 때 유용합니다.
윈도우 경로를 쓰실 때는 C:\Users\이름\Documents\보고서.hwp처럼 말하면 됩니다. 파일 이름에 한글이나 공백이 있어도 되지만, 경로에서 한 글자만 틀려도 파일을 못 찾았다는 응답이 오니 탐색기에서 경로를 복사해 붙이시는 쪽이 낫습니다.
회사 문서를 읽힐 때 꼭 해둘 보안 설정
여기서 한 번은 멈춰서 생각해 보셔야 합니다. MCP 서버는 내 컴퓨터에서 도는 프로그램이어서 기본적으로 컴퓨터 안의 파일에 접근할 수 있습니다. Claude가 엉뚱한 폴더의 파일을 열어 보는 일을 막고 싶다면, kordoc 공식 문서에 나온 환경 변수로 범위를 제한하세요. KORDOC_ROOT에 폴더를 지정하면 MCP의 파일 접근이 그 폴더 안으로 제한됩니다. 설정 파일에서는 env 항목으로 넣습니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"],
"env": {
"KORDOC_ROOT": "/Users/내이름/Documents/업무문서"
}
}
}
}또 하나 짚을 점이 있습니다. kordoc이 파일을 로컬에서 처리한다는 것과, 변환된 내용이 Claude의 대화에 올라간다는 것은 별개의 이야기입니다. 문서 내용을 읽어 달라고 요청하면 그 텍스트는 대화에 담겨 Claude 서비스로 전달됩니다. 로컬 OCR이니까 안전하다고 생각하기 쉽지만, 대화창에 올라가는 순간부터는 회사의 AI 사용 규정이 적용되는 범위입니다. 개인정보나 대외비가 들어 있는 문서라면 사용 전에 사내 기준을 확인하세요. 개인정보를 먼저 가리고 싶다면 redact_document 도구가 있는데, 이것도 자동 탐지 보조 도구라서 결과를 사람이 최종 확인해야 하고 이미지 속 글자는 탐지하지 못한다고 문서에 분명히 적혀 있습니다.
Claude Code에서는 플러그인으로 쓰기
Claude Code를 쓰신다면 설정 파일을 만질 필요 없이 플러그인으로도 쓸 수 있습니다. kordoc 문서에 나온 설치 방법은 이렇습니다.
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc첫 줄이 마켓플레이스를 추가하는 명령이고, 둘째 줄이 설치입니다. 설치 후에는 HWP나 HWPX 파일을 언급하거나 공문서를 만들어 달라고 요청할 때 kordoc 스킬이 자동으로 켜진다고 합니다. 따로 도구를 지정하지 않아도 되는 점이 MCP 직접 등록과의 차이입니다.
처음 연결하고 막히기 쉬운 지점 정리
앞에서 흩어져 나온 내용을 한 번에 정리해 드립니다. 도구가 안 보이면 먼저 Node.js가 20 이상인지 보세요. 설정을 고쳤는데 반영이 안 된다면 앱을 창만 닫은 것은 아닌지 확인하세요. 설정 파일을 저장한 뒤 앱이 아예 켜지지 않거나 서버 오류가 뜬다면 JSON의 쉼표와 괄호를 의심하세요. 윈도우에서 npx를 못 찾는다는 오류가 나오면 cmd와 /c를 쓰는 방식으로 바꾸세요. 파일을 못 찾았다는 응답이 오면 경로를 한 글자씩 대조해 보세요. 첫 실행이 유난히 느리다면 npx가 패키지를 내려받는 중이라서 그렇고, 두 번째부터는 빨라집니다.
마무리, 연결은 한 번이고 활용은 매일입니다
정리하면 kordoc을 Claude에 붙이는 방법은 두 가지입니다. npx -y kordoc setup으로 마법사에 맡기거나, claude_desktop_config.json에 서버 정보를 직접 넣는 방법입니다. 둘 다 끝나면 Claude Desktop을 완전히 껐다 켜야 하고, 연결 후에는 파일 경로만 알려 주면 Claude가 HWP를 읽고, 표를 뽑고, 두 문서를 비교해 줍니다.
연결 자체는 5분이면 끝납니다. 중요한 것은 그다음입니다. 회사에서 쓸 거라면 KORDOC_ROOT로 접근 범위를 좁혀 두고, 문서가 대화창으로 올라간다는 점을 염두에 두세요.
다음 글에서는 kordoc의 쓰기 기능을 다룹니다. 읽은 문서에서 멈추지 않고 신청서 양식을 자동으로 채우고, 마크다운으로 쓴 초안을 공문서 형식의 HWPX로 뽑아내는 방법을 이어 가겠습니다.