ai.smithery/airmang-hwpx-mcp

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

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

왜 필요한가?

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

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

• ✅ 운영체제 무관 — Windows, macOS, Linux에서 동작
• ✅ 한글 워드프로세서 불필요 — 순수 파이썬 기반 처리
• ✅ AI 연동 중심 — Claude Desktop, VS Code, Gemini CLI 등 MCP 클라이언트와 직접 연결
• ✅ 일관된 호출 방식 — 도구 호출마다 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.6

현재 저장소 기준 검증 버전은 python-hwpx 2.7.1입니다.

2. MCP 클라이언트 설정

claude_desktop_config.json

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

~/.gemini/settings.json

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

.vscode/mcp.json

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

각 에디터의 MCP 설정 파일에 같은 블록을 추가하면 됩니다.

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

주요 기능

기본 모드에서 주요 HWPX 편집 도구를 제공하며, 고급 모드(HWPX_MCP_ADVANCED=1)에서는 점검·검증용 도구가 추가로 활성화됩니다.

📖 읽기 및 탐색

🔎 검색 및 치환

✏️ 문서 편집

📊 표 편집

🎨 서식 및 스타일

스타일 참조 팁: add_paragraph(..., style=...)와 insert_paragraph(..., style=...)는 list_styles의 id, create_custom_style이 반환하는 style_id, 스타일 이름을 모두 받을 수 있습니다.

📤 추출

🔬 고급 도구

HWPX_MCP_ADVANCED=1일 때 활성화:

환경 변수

환경 변수 포함 MCP 설정 예시:

{
  "mcpServers": {
    "hwpx": {
      "command": "uvx",
      "args": ["hwpx-mcp-server"],
      "env": {
        "HWPX_MCP_MAX_CHARS": "12000",
        "HWPX_MCP_AUTOBACKUP": "1",
        "HWPX_MCP_ADVANCED": "0",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

테스트

# 테스트 의존성 설치
python -m pip install -e ".[test]"

# 전체 테스트
python -m pytest -q

추가 참고:

• 사용 사례: docs/use-cases.md
• 종합 리포트: tests/hwpx_mcp_report_updated.md
• 스킬 기반 워크플로: docs/skill-first-workflows.md

라이선스

MIT

작성자

고규현 — 광교고등학교 정보·컴퓨터 교사

• 이메일: kokyuhyun@hotmail.com
• GitHub: @airmang