📄 hwpx-mcp-server

AI 에이전트가 HWPX 문서를 바로 읽고, 찾고, 수정하게 만드는 MCP 서버

한글 워드프로세서 없이 · 순수 파이썬 · 크로스 플랫폼

🧩 HWPX Stack (3종)

hwpx-mcp-server는 모델 컨텍스트 프로토콜(MCP) 표준을 따르는 서버로, python-hwpx 기반에서 HWPX 문서의 열람 · 검색 · 편집 · 추출을 AI 클라이언트에서 직접 수행할 수 있게 합니다.

참고 이 서버는 Open XML 기반 .hwpx 포맷을 지원합니다. 바이너리 .hwp 포맷은 직접 편집 대상이 아닙니다.

이 서버가 바로 해결하는 일

• Claude Desktop, VS Code, Gemini CLI 같은 MCP 클라이언트에서 HWPX를 바로 읽기
• 복사본을 만든 뒤 안전하게 검색·치환·표 편집·문단 추가 수행
• 문서 개요, 표 맵, 패키지 구조를 AI가 직접 조회하고 후속 작업으로 연결
• 한글 워드프로세서 없이 서버·CI·로컬 개발 환경에서 같은 흐름 유지
• 고급 모드에서 검증, package inspection, edit planning까지 확장

Claude Desktop 5분 연결

아래 설정 하나만 넣으면 Claude Desktop에서 hwpx MCP 서버를 바로 잡는다.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}

Screenshot placeholder: Claude Desktop 설정 화면에서 hwpx 서버가 활성화된 장면을 여기에 넣을 예정.

왜 필요한가?

국내 공공기관·학교·기업에서는 한글 문서 기반 업무가 많지만, 자동화는 오랫동안 운영체제와 프로그램에 크게 의존했습니다.

hwpx-mcp-server는 이 제약을 줄이는 데 초점을 둡니다.

• ✅ 운영체제 무관 — Windows, macOS, Linux에서 동작
• ✅ 한글 워드프로세서 불필요 — 순수 파이썬 기반 처리
• ✅ AI 연동 중심 — Claude Desktop, VS Code, Gemini CLI 등 MCP 클라이언트와 직접 연결
• ✅ 문서 편집을 도구 호출로 표준화 — 읽기, 편집, 복제, 검증을 MCP 도구 집합으로 노출
• ✅ 실전 작업 흐름에 맞춘 설계 — read, copy, edit, inspect, validate를 한 서버 표면으로 정리
• ✅ 일관된 호출 방식 — 도구 호출마다 filename을 명시하는 stateless 구조

사용 사례

• 실전 사용 사례: docs/use-cases.md
• 종합 테스트 리포트: tests/hwpx_mcp_report_updated.md

빠른 시작

1. 설치 및 실행

uv 기준:

uvx hwpx-mcp-server

또는 pip 설치 후 실행:

pip install hwpx-mcp-server
hwpx-mcp-server

요구 사항:

• Python >= 3.10
• python-hwpx >= 2.11.1

현재 저장소 기준 검증 버전은 python-hwpx 2.11.1입니다 (2026-06-12 검증). 최소 지원 버전은 python-hwpx >= 2.11.1입니다.

2. MCP 클라이언트 설정

HWPX plugin companion launcher

The hwpx-plugins repository builds per-host bundles whose MCP launcher (plugins/<host>/hwpx-plugin/scripts/hwpx-mcp-server) can run this server. In local development, set HWPX_MCP_SERVER_REPO=/absolute/path/to/hwpx-mcp-server and PYTHON_HWPX_REPO=/absolute/path/to/python-hwpx when the repositories are not under a common parent. The launcher otherwise discovers them by walking up from the bundle directory and uses uv run --project "$HWPX_MCP_SERVER_REPO" --with-editable "$PYTHON_HWPX_REPO" --with-editable "$HWPX_MCP_SERVER_REPO" hwpx-mcp-server.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"]
    }
  }
}