HWP-MCP (한글 문서 MCP 서버) 설치·사용법 — AI 어시스턴트가 한글(.hwp/.hwpx)

한글(.hwp/.hwpx) 문서를 AI 어시스턴트와 연동하고 싶다면 hwp-mcp MCP 서버를 Claude 또는 Cursor에 설치하면 됩니다. 이 가이드는 준비물 확인부터 설정 파일 수정, 실제 작동 확인까지 전 과정을 단계별로 설명합니다. API 키는 필요 없으며, Node.js가 설치된 환경이라면 수 분 안에 완료할 수 있습니다.

왜 한글 문서 MCP가 필요한가

한국의 공공기관·학교·기업은 여전히 한컴 한글(.hwp/.hwpx) 형식의 문서를 광범위하게 사용합니다. 그러나 기존 AI 어시스턴트는 Word(.docx)나 PDF는 쉽게 읽지만, 한글 전용 포맷은 직접 지원하지 않습니다. 매번 파일을 PDF로 변환해 업로드하는 번거로운 과정이 반복됩니다.

MCP(Model Context Protocol) 서버를 활용하면 Claude 같은 AI 어시스턴트가 로컬에 있는 .hwp/.hwpx 파일을 직접 읽고, 내용을 요약하거나 편집 지시를 수행할 수 있습니다. 변환 과정 없이 원본 파일 그대로 AI와 소통하는 것입니다.

hwp-mcp란 무엇인가

hwp-mcp는 개발자 treesoop이 오픈소스로 공개한 MCP 서버입니다. AI 어시스턴트가 한글(.hwp/.hwpx) 문서를 읽고 편집·생성할 수 있도록 돕는 브리지 역할을 합니다. npx 명령 하나로 서버를 실행할 수 있어 별도 설치 과정이 간단합니다.

주요 기능 요약

기능	설명
문서 읽기	.hwp / .hwpx 파일 내용을 텍스트로 파싱
문서 편집	AI 지시에 따라 내용 수정
문서 생성	새로운 한글 문서 생성
API 키 불필요	무료, 별도 계정 없이 사용

데이터 흐름

사용자 (Claude Desktop / Cursor)
        ↓ 자연어 지시
  hwp-mcp MCP 서버 (로컬 실행)
        ↓ 파일 파싱
  로컬 .hwp / .hwpx 파일
        ↓ 텍스트 반환
  AI 어시스턴트 (Claude 등)
        ↓ 요약 / 편집 / 생성
  사용자 응답

준비물

• Node.js 18 이상 — node --version 으로 확인. 없으면 nodejs.org에서 LTS 버전 설치
• Claude Desktop 또는 MCP를 지원하는 다른 클라이언트(Cursor, Continue 등)
• 연동하려는 한글 문서 파일(.hwp 또는 .hwpx)

단계별 설치 방법

1단계: Node.js 설치 확인

node --version
# v18.0.0 이상이면 준비 완료

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

Claude Desktop의 MCP 설정은 아래 경로의 claude_desktop_config.json 파일에서 관리합니다.

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

파일이 없다면 새로 생성하세요.

3단계: MCP 서버 설정 추가

claude_desktop_config.json 파일을 열고 아래 내용을 추가합니다.

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

이미 다른 MCP 서버가 등록돼 있다면 mcpServers 블록 안에 "hwp-mcp" 항목만 추가하면 됩니다.

4단계: Claude Desktop 재시작

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료했다가 다시 실행합니다. 트레이 아이콘이나 작업 관리자에서 프로세스가 완전히 종료됐는지 확인하세요.

5단계: 한글 문서 연동 확인

Claude를 열고 아래와 같이 입력해 봅니다.

/Users/yourname/documents/report.hwpx 파일의 내용을 요약해 줘.

Claude가 파일 내용을 읽어 요약을 제공하면 정상적으로 연동된 것입니다.

Cursor에서 hwp-mcp 설정하기

Cursor를 사용한다면 프로젝트 루트의 .cursor/mcp.json 파일에 동일한 형식으로 추가합니다.

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

Cursor를 재시작하면 AI 채팅 창에서 한글 문서를 직접 참조할 수 있습니다.

함께 쓰면 좋은 MCP 서버

hwp-mcp 외에도 한글 문서 관련 MCP 서버가 있습니다. 용도에 따라 선택하거나 함께 사용할 수 있습니다.

서버	특징	설치 명령
HWP-MCP	.hwp/.hwpx 읽기·편집·생성	npx -y hwp-mcp
코르독 (KorDoc)	HWP·HWPX·PDF·XLSX·DOCX → Markdown 변환	npx -y kordoc setup
한포지 (HwpForge)	HWPX 읽기·쓰기·변환 (KS X 6101 표준)	npx -y @hwpforge/mcp

코르독(KorDoc)은 한글 공문서를 Markdown으로 변환하는 데 특화돼 있어 문서 형식 변환이 주 목적이라면 함께 사용하면 좋습니다. 한포지(HwpForge)는 한컴의 공식 HWPX 표준(KS X 6101)을 지원해 보다 정확한 파싱이 필요할 때 유용합니다.

개발 도구 카테고리에서 더 많은 MCP 서버를 둘러보거나, 전체 서버 목록에서 원하는 서버를 찾아볼 수 있습니다.

흔한 오류와 해결 방법

”spawn npx ENOENT” 오류

Node.js가 설치되지 않았거나 PATH에 등록되지 않은 경우 발생합니다. node --version과 npx --version으로 설치를 확인하고, 설치 후 Claude Desktop을 재시작하세요.

MCP 서버가 목록에 나타나지 않음

JSON 형식 오류가 원인인 경우가 많습니다. 설정 파일을 JSON 유효성 검사 도구(예: jsonlint.com)에 붙여넣어 문법 오류를 확인하세요. 특히 마지막 항목 뒤의 쉼표(trailing comma)는 오류를 유발합니다.

파일 경로를 인식하지 못함

파일 경로에 공백이나 한글이 포함된 경우 따옴표로 감싸거나, 경로를 영문으로 변경해 보세요. Windows에서는 역슬래시(\) 대신 슬래시(/)를 사용하거나 역슬래시를 두 번(\\) 입력해야 합니다.

파일 내용이 깨져서 출력됨

매우 오래된 .hwp 포맷(97년 이전 버전 등)은 파싱이 불완전할 수 있습니다. 이 경우 한포지(HwpForge)나 코르독(KorDoc) 서버를 대안으로 시도해 보세요.

자주 묻는 질문

Q. hwp-mcp를 사용하려면 API 키가 필요한가요?

아니요. hwp-mcp는 API 키 없이 무료로 사용할 수 있습니다. Node.js 환경만 갖춰져 있으면 별도 계정 등록 없이 바로 실행됩니다.

Q. 구형 .hwp 파일도 읽을 수 있나요?

hwp-mcp는 .hwp와 .hwpx 모두 지원하도록 설계됐습니다. 다만 매우 오래된 버전의 파일은 파싱이 불완전할 수 있으니 GitHub 이슈 트래커에서 지원 현황을 확인하세요.

Q. Windows에서도 동작하나요?

네. hwp-mcp는 Node.js 기반이므로 Windows, macOS, Linux 모두에서 동작합니다. 다만 한글 프로그램 자체가 설치된 환경에서 더 안정적으로 작동할 수 있습니다.

Q. Cursor나 다른 MCP 클라이언트에서도 쓸 수 있나요?

네. MCP 프로토콜을 지원하는 클라이언트라면 Claude Desktop 외에 Cursor, Continue 등에서도 동일하게 설정할 수 있습니다.

Q. 한글 문서를 편집하고 저장하는 것도 가능한가요?

hwp-mcp는 문서 읽기뿐 아니라 편집·생성 기능도 제공합니다. 실제 편집 범위는 서버 버전에 따라 다를 수 있으므로 GitHub 저장소의 README를 확인하세요.

Q. 오류가 발생하면 어디서 도움을 받을 수 있나요?

GitHub 저장소(https://github.com/treesoop/hwp-mcp)의 Issues 탭에 문의하거나, MCP모아 서버 상세 페이지를 활용하세요.

다음 단계

hwp-mcp 설치가 완료됐다면 이제 본격적으로 활용해 볼 차례입니다.

• 공문서 자동 요약: 매일 쌓이는 한글 보고서를 Claude에게 요약시켜 시간을 절약하세요.
• 문서 초안 생성: “이 양식을 참고해 새 보고서를 작성해 줘”라고 지시하면 AI가 초안을 생성합니다.
• 다른 형식으로 변환: 코르독(KorDoc)을 함께 사용하면 HWP 문서를 Markdown이나 다른 형식으로 변환할 수 있습니다.

더 많은 MCP 서버가 궁금하다면 전체 서버 목록을 방문하거나, 직접 개발한 MCP 서버가 있다면 MCP모아에 등록해 한국 개발자 커뮤니티와 공유해 보세요.