MCP HWPX 서버
mcp-hwpx는 python-hwpx를 이용해 한글 HWPX 문서를 읽고 편집하는 Model Context Protocol(MCP) STDIO 서버입니다. Smithery 레지스트리를 통해 한 줄 설치와 클라이언트 등록을 지원하며, 로컬 워크스페이스 내부의 문서를 안전하게 다룰 수 있도록 설계되었습니다.
주요 기능
- HWPX 문서 생성, 열기, 저장, 메타데이터 조회
- 문단/표/이미지 삽입과 기본 미리보기 지원
- 워크스페이스 경로 검증 및 자동 백업(.bak) 파일 생성
hwpx:list,hwpx:preview(path)리소스를 통한 파일 인벤토리/미리보기 제공- Windows, macOS, Linux에서 Python 3.10 이상 지원
요구 사항
- Python 3.10 이상
- Node.js 환경( Smithery CLI 설치용 )
- 로컬에 HWPX 문서를 저장할 디렉터리 권한
Smithery를 통한 한 줄 설치
사전에 Smithery CLI가 설치되어 있지 않다면 아래 명령으로 설치합니다.
그 다음 아래 명령 한 줄로 서버 설치와 클라이언트 등록을 동시에 수행할 수 있습니다.
Gemini CLI를 사용하는 경우:
설치가 완료되면 Claude Desktop 또는 Gemini CLI에서 "mcp-hwpx"를 서버로 추가하고, 워크스페이스 디렉터리를 지정하면 준비가 끝납니다.
도구 및 리소스 목록
| 이름 | 유형 | 설명 |
|---|---|---|
set_workspace | Tool | 워크스페이스 디렉터리를 설정합니다. |
open_document | Tool | 기존 HWPX 파일을 열고 메타데이터를 로드합니다. |
create_document | Tool | 새 HWPX 파일을 생성합니다. |
insert_paragraph | Tool | 문단을 추가합니다. |
insert_table | Tool | 행/열 수를 지정하여 표를 추가합니다. |
insert_image | Tool | 워크스페이스 내 이미지를 문서에 삽입합니다. |
get_metadata | Tool | 현재 열린 문서의 메타데이터를 반환합니다. |
save_as | Tool | 다른 이름으로 문서를 저장합니다. |
hwpx:list | Resource | 워크스페이스 내 HWPX 파일 목록(JSON). |
hwpx:preview(path) | Resource | 지정한 문서의 앞부분 문단 미리보기(JSON). |
로컬 설치 (대체 옵션)
Smithery 없이 직접 설치하고 실행할 수 있습니다.
소스에서 개발 모드로 설치할 경우:
로컬에서 서버를 실행하려면 다음 명령을 사용합니다.
ZIP 패키지 배포
scripts/build_zip_unix.sh 또는 scripts/build_zip_win.ps1를 실행하면 의존성(requirements.txt)과 함께 동작 가능한 ZIP 패키지가 dist/mcp-hwpx-zip.zip으로 생성됩니다. 이 파일에는 서버 실행을 위한 스크립트와 문서가 포함되어 있어 오프라인 환경에서도 설치할 수 있습니다.
보안 및 워크스페이스 정책
- 모든 파일 경로는 지정한 워크스페이스 내부로 제한됩니다. 워크스페이스 밖의 경로를 요청하면
SecurityError로 거부됩니다. - 기존 문서를 수정하기 전 자동으로
.bak백업 파일을 생성합니다. - 네트워크 접근은 사용하지 않으며 STDIO를 통해서만 통신합니다.
작동 확인 예시
set_workspace도구를 호출해 로컬 디렉터리를 설정합니다.create_document로 새 문서를 만들고insert_paragraph,insert_table,insert_image를 이용해 내용을 추가합니다.get_metadata를 호출해 문단/표 개수를 확인합니다.save_as로 결과물을 다른 이름으로 저장합니다.hwpx:list리소스를 읽어 새로 저장된 문서가 목록에 있는지 확인합니다.
테스트
개발 환경에서 다음 명령으로 테스트를 실행할 수 있습니다.
라이선스
이 프로젝트는 MIT 라이선스로 배포됩니다.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
Enables reading, editing, and creating Korean HWPX documents through python-hwpx library. Supports document creation, paragraph/table/image insertion, metadata management, and workspace-restricted file operations with automatic backup functionality.