hwpx-mcp-server 0.5.0

Model Context Protocol server for local HWPX document automation.

한글 MCP (HWPX) 서버 - 한글 자동화 HWPX 문서 자동 생성·편집·검증mcp

이 프로젝트는 한글 MCP(HWPX) 서버로, HWPX 문서를 한글 워드프로세서 없이 직접 열고 자동화할 수 있도록 설계되었습니다.
Gemini CLI, Claude Desktop과 같은 MCP 클라이언트에 연결하여 문서 생성·편집·탐색 기능을 제공합니다.

순수 파이썬으로 HWPX 문서를 자유롭게 다루는 가장 강력한 방법.

hwpx-mcp-server는 Model Context Protocol 표준을 따르는 서버로, 강력한 python-hwpx 라이브러리를 기반으로 합니다. Gemini, Claude와 같은 최신 AI 클라이언트와 완벽하게 연동하여 한글 워드 프로세서 로컬 HWPX 문서를 열람, 검색, 편집, 저장하는 풍부한 기능을 제공합니다.

---

✨ 주요 기능

• ✅ 표준 MCP 서버 구현: 공식 mcp SDK를 사용하여 안정적인 표준 입/출력 기반 서버를 제공합니다.
• 📂 제로 설정: 별도 설정 없이 현재 작업 디렉터리를 기준으로 즉시 경로를 처리합니다.
• 📄 강력한 문서 편집: 텍스트 추출, 페이지네이션부터 스타일, 표, 메모, 개체 편집까지 모두 가능합니다.
• 🛡️ 안전한 저장: 자동 백업(*.bak) 옵션으로 예기치 않은 데이터 손실을 방지합니다.
• 🚀 즉시 실행: uv만 있으면 uvx hwpx-mcp-server 한 줄로 바로 시작할 수 있습니다.

🚀 빠른 시작

1. uv 설치

가장 먼저 파이썬 패키지 설치 도구인 uv를 설치하세요. 👉 Astral uv 설치 가이드

2. MCP 클라이언트 설정

방법 1: 로컬 설치 (uvx 사용)

사용 중인 MCP 클라이언트 설정에 아래와 같이 서버 정보를 추가하세요.

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"],
      "env": {
        "HWPX_MCP_PAGING_PARA_LIMIT": "200",
        "HWPX_MCP_AUTOBACKUP": "1",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

터미널에서 직접 실행:

uvx hwpx-mcp-server

uvx 명령은 첫 실행 시 필요한 종속성을 자동으로 설치하며, 반드시 python-hwpx 1.9 이상의 버전이 준비되어야 합니다.

방법 2: HTTP 스토리지 모드

원격 문서 서버와 연동하려면 HTTP 백엔드 설정을 추가하세요.

{
  "mcpServers": {
    "hwpx-http": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"],
      "env": {
        "HWPX_STORAGE_BACKEND": "http",
        "HWPX_HTTP_BASE_URL": "https://your-server.com/documents",
        "HWPX_MCP_PAGING_PARA_LIMIT": "200",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

HTTP 모드에서는 uri 필드를 사용하여 원격 문서를 지정할 수 있습니다. 서버는 실행된 현재 디렉터리를 기준으로 경로를 해석하므로, 별도의 작업 디렉터리 설정 없이 바로 사용할 수 있습니다.

⚙️ 환경 변수

변수	설명	기본값
HWPX_MCP_PAGING_PARA_LIMIT	페이지네이션 최대 문단 수	200
HWPX_MCP_AUTOBACKUP	저장 전 .bak 백업 생성 (1/0)	0
LOG_LEVEL	로그 레벨 (INFO/DEBUG 등)	INFO
HWPX_MCP_HARDENING	하드닝 파이프라인 활성화 (1/0)	0
HWPX_STORAGE_BACKEND	스토리지 백엔드 (local/http)	local
HWPX_HTTP_BASE_URL	HTTP 모드 시 베이스 URL	-

🛠️ 제공 도구

다양한 문서 편집 및 관리 도구를 제공합니다. 주요 도구는 다음과 같습니다:

• 문서 조회: open_info, read_text, read_paragraphs, find
• 문서 편집: replace_text_in_runs, add_paragraph, add_table, set_table_cell_text
• 스타일 관리: ensure_run_style, apply_style_to_text_ranges
• 파일 저장: save, save_as, make_blank
• 하드닝 모드 (HWPX_MCP_HARDENING=1): hwpx.plan_edit, hwpx.preview_edit, hwpx.apply_edit, hwpx.search, hwpx.get_context

📖 전체 도구 목록과 상세 파라미터는 ListTools 응답의 JSON 스키마를 참고하세요.

🧪 테스트

python -m pip install -e .[test]
python -m pytest

🧑‍💻 개발 참고

• python-hwpx>=1.9, mcp, pydantic 등 순수 파이썬으로 구성
• 모든 편집 작업은 dryRun 플래그 지원
• 자동 백업(.bak) 옵션으로 데이터 보호
• JSON 스키마는 draft-07 호환 형태로 제공

📜 라이선스

이 프로젝트는 MIT 라이선스로 배포됩니다. 자세한 내용은 라이선스 파일을 확인하세요.

이메일

광교고등학교 교사 고규현 : [e-mail]