한포지(HwpForge) 설치·사용법 — 한글(HWPX) 문서를 AI 에이전트가 읽고

한포지(HwpForge) MCP 서버를 Claude Desktop 또는 Cursor에 설치하면 AI가 한컴 한글(HWPX) 문서를 직접 읽고, 수정하고, 다른 형식으로 변환할 수 있습니다. 별도의 API 키 없이 npx 한 줄로 설치가 완료되며, 설정 파일에 항목을 추가하고 재시작하는 것만으로 바로 사용할 수 있습니다. 이 가이드는 설치부터 실제 동작 확인, 흔한 오류 해결까지 단계별로 안내합니다.

왜 한포지(HwpForge) MCP가 필요한가

한국 공공기관, 학교, 기업에서는 여전히 한컴 한글(HWP/HWPX) 형식의 문서가 광범위하게 사용됩니다. 그런데 기존 AI 도구는 HWPX 파일을 이해하지 못해, 사용자가 직접 내용을 복사·붙여넣기하거나 따로 변환해야 하는 번거로움이 있었습니다.

한포지(HwpForge)는 이 문제를 해결하는 MCP(Model Context Protocol) 서버입니다. MCP를 통해 AI 에이전트가 HWPX 파일을 직접 열고, 내용을 읽고, 수정하고, 다른 형식으로 변환하는 도구를 실행할 수 있게 됩니다. 한컴이 제정한 공개 표준 KS X 6101을 기반으로 동작하므로, 표준 HWPX 파일이라면 안정적으로 처리할 수 있습니다.

[사용자] → [Claude / Cursor] → [HwpForge MCP 서버] → [HWPX 파일(KS X 6101)]
                                        ↓
                               [읽기 / 쓰기 / 변환 결과 반환]

준비물

항목	최소 버전 / 조건
Node.js	18 이상 (node -v로 확인)
npm / npx	Node.js 설치 시 자동 포함
Claude Desktop 또는 Cursor	MCP 지원 버전
HWPX 파일	KS X 6101 표준 형식

Node.js가 설치되어 있지 않다면 nodejs.org에서 LTS 버전을 먼저 설치하세요.

단계별 설치 방법

1단계: Node.js 환경 확인

터미널(macOS: 터미널 앱, Windows: PowerShell)을 열고 다음 명령어를 실행합니다.

node -v
npx -v

Node.js 18 이상, npx가 정상 출력되면 준비 완료입니다.

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

Claude Desktop의 MCP 설정 파일은 운영체제별로 다음 위치에 있습니다.

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

파일이 없다면 새로 만들면 됩니다. 텍스트 편집기(VS Code, 메모장 등)로 엽니다.

3단계: HwpForge MCP 서버 항목 추가

설정 파일에 아래 내용을 추가합니다. 이미 다른 MCP 서버가 있다면 mcpServers 블록 안에 항목만 추가하세요.

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

-y 플래그는 패키지를 자동으로 설치·업데이트하는 옵션입니다. 별도로 npm install을 실행하지 않아도 됩니다.

다른 MCP 서버와 함께 사용하는 경우 예시:

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    },
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

4단계: Claude Desktop 재시작

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 실행합니다. macOS라면 메뉴 막대의 Claude 아이콘을 우클릭해 “종료”를 선택하거나 Cmd+Q로 완전 종료합니다.

5단계: 연결 확인

Claude 채팅창에서 HWPX 파일 경로를 알려주고 문서 내용을 요청해 보세요.

/Users/username/Documents/보고서.hwpx 파일의 내용을 요약해 줘.

AI가 파일을 직접 열어 내용을 읽어 답변한다면 설치 성공입니다.

데이터 흐름 한눈에 보기

Claude Desktop / Cursor
        │
        │ MCP 프로토콜 (stdio)
        ▼
HwpForge MCP 서버 (@hwpforge/mcp)
        │
        │ KS X 6101 파서
        ▼
  .hwpx 파일 (로컬 디스크)
        │
        │ 파싱 결과 (텍스트·구조 데이터)
        ▼
  AI 응답 생성

HwpForge는 로컬에서만 동작하므로 문서 내용이 외부 서버로 전송되지 않습니다. 보안이 중요한 내부 문서에도 안심하고 사용할 수 있습니다.

Cursor에서 설치하는 방법

Cursor는 .cursor/mcp.json 파일로 MCP 서버를 관리합니다. 프로젝트 루트 또는 홈 디렉터리에 파일을 만들고 아래처럼 작성합니다.

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

저장 후 Cursor를 재시작하면 MCP 패널에서 hwpforge 도구가 보입니다.

흔한 오류와 해결 방법

오류 1: “command not found: npx”

Node.js가 설치되지 않았거나 PATH에 등록되지 않은 경우입니다.

# macOS (Homebrew)
brew install node

# Windows (winget)
winget install OpenJS.NodeJS.LTS

설치 후 터미널을 새로 열고 npx -v를 다시 확인합니다.

오류 2: 설정 저장 후에도 도구 목록에 나타나지 않음

JSON 문법 오류가 가장 흔한 원인입니다. 설정 파일을 JSONLint 같은 검사 도구에 붙여넣어 문법을 확인하세요. 특히 마지막 항목 뒤의 쉼표(trailing comma)가 있으면 오류가 납니다.

오류 3: HWPX 파일을 열 수 없다는 오류

파일 경로에 한글이나 공백이 포함된 경우 경로 표기에 주의가 필요합니다. 문서를 영문 경로의 폴더로 복사해 테스트해 보세요.

오류 4: 구버전 .hwp 파일이 인식되지 않음

HwpForge는 KS X 6101 표준의 HWPX 형식을 지원합니다. 구버전 .hwp 파일은 한컴 오피스에서 “다른 이름으로 저장 → HWPX” 방식으로 먼저 변환하세요.

관련 서버 비교

비슷한 역할의 한글 문서 처리 MCP 서버를 비교합니다.

서버	지원 형식	특징
한포지(HwpForge)	HWPX	읽기·쓰기·변환, KS X 6101 표준
코르독(KorDoc)	HWP·HWPX·PDF·XLSX·DOCX	다양한 공문서 형식을 Markdown으로 변환
HWP-MCP	HWP·HWPX	읽기·편집·생성 지원

한 가지 형식만 처리하면 된다면 HwpForge로 충분합니다. 여러 공문서 형식을 함께 다뤄야 한다면 코르독(KorDoc)을 병행하는 것을 고려해 보세요. 개발도구 카테고리에서 더 많은 한국형 MCP 서버를 확인할 수 있습니다.

자주 묻는 질문

HwpForge MCP는 무료인가요?

네, 오픈소스 프로젝트로 무료입니다. API 키가 필요 없으며 GitHub 저장소에서 소스를 직접 확인할 수 있습니다.

한글(.hwp) 구버전 파일도 읽을 수 있나요?

HwpForge는 공식적으로 HWPX(KS X 6101) 형식을 지원합니다. 구버전 .hwp 파일은 한컴 오피스에서 HWPX로 변환한 뒤 사용하시기 바랍니다.

Cursor나 VS Code에서도 사용할 수 있나요?

네, MCP를 지원하는 모든 클라이언트(Claude Desktop, Cursor, Continue 등)에서 동일한 방법으로 설정할 수 있습니다.

설치 후 도구 목록에 hwpforge가 보이지 않으면 어떻게 하나요?

JSON 설정 파일의 문법 오류(쉼표 누락, 괄호 불일치)를 먼저 확인하세요. 그 다음 Claude Desktop을 완전히 종료하고 재시작합니다. 그래도 안 되면 터미널에서 npx -y @hwpforge/mcp를 직접 실행해 오류 메시지를 확인하세요.

HWPX 문서 편집 후 저장도 되나요?

HwpForge는 읽기뿐 아니라 쓰기·변환 기능도 제공합니다. 구체적인 지원 도구 목록은 GitHub 저장소의 README를 참고하세요.

여러 HWPX 파일을 한꺼번에 처리할 수 있나요?

AI 에이전트에게 파일 경로를 여러 개 제시하거나 디렉터리를 알려주면 순차적으로 처리할 수 있습니다. 다만 한 번에 처리 가능한 양은 클라이언트의 컨텍스트 한도에 따라 달라집니다.

다음 단계

한포지(HwpForge) 설치를 마쳤다면 다음을 시도해 보세요.

• HWPX 문서 자동 요약: 긴 공문서를 AI에게 요약 요청
• HWPX to Markdown 변환: 문서 내용을 다른 시스템으로 이전
• 일괄 처리 자동화: 여러 HWPX 파일을 에이전트가 순서대로 처리

더 많은 한국형 MCP 서버는 MCP 서버 목록에서 확인하거나, 개발도구 카테고리를 둘러보세요. 새로운 한국형 MCP 서버를 발견했다면 등록 신청을 통해 MCP모아에 추가할 수 있습니다.