HWP MCP Server

  

한글(HWP) 문서를 AI 어시스턴트가 제어할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

Windows 환경에서 한글 프로그램의 COM 인터페이스를 활용하여 HWP/HWPX 문서를 완벽하게 읽고, 쓰고, 편집할 수 있습니다.

Features

• 문서 관리: 생성, 열기, 저장, 닫기
• 텍스트 편집: 삽입, 검색, 치환, 삭제
• 표 조작: 생성, 셀 편집, 행/열 추가/삭제
• 서식 적용: 글꼴, 정렬, 스타일
• 이미지 삽입: 이미지 추가 및 크기 조정
• 내보내기: PDF, 텍스트 변환

Requirements

| 항목 | 요구사항 | | ---- | -------- | | OS | Windows 10/11 | | 한글 | 2010 이상 (HWPFrame.HwpObject 지원) | | Python | 3.10+ | | MCP Client | Claude Desktop, Claude Code 등 |

Installation

# 저장소 클론
git clone https://github.com/realcoding2003/readwrite-hwp-mcp.git
cd readwrite-hwp-mcp

# 의존성 설치
pip install -r requirements.txt

Configuration

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json 파일에 추가:

{
  "mcpServers": {
    "hwp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "C:\\path\\to\\readwrite-hwp-mcp"
    }
  }
}

Claude Code (CLI)

claude mcp add hwp python -m src.server --cwd /path/to/readwrite-hwp-mcp

Usage

MCP 클라이언트에서 사용 가능한 도구 예시:

# 새 문서 생성
hwp_create

# 문서 열기
hwp_open path="C:\Documents\report.hwp"

# 텍스트 삽입
hwp_insert_text text="안녕하세요"

# 표 생성
hwp_create_table rows=3 cols=4

# PDF 내보내기
hwp_export_pdf path="C:\Documents\report.pdf"

MCP Tools

MVP (1단계)

| 도구 | 설명 | | ---- | ---- | | hwp_connect | 한글 프로그램 연결 | | hwp_create | 새 문서 생성 | | hwp_open | 문서 열기 | | hwp_save | 문서 저장 | | hwp_insert_text | 텍스트 삽입 | | hwp_create_table | 표 생성 |

전체 도구 목록은 API 문서를 참조하세요.

Documentation

| 문서 | 설명 | | ---- | ---- | | 기획서 | 프로젝트 기획 및 로드맵 | | 아키텍처 | 시스템 구조 | | 배포 가이드 | 설치 및 실행 | | API 문서 | MCP 도구 상세 |

Development

# 개발 환경 설정
pip install -r requirements-dev.txt

# 테스트 실행
pytest

# 린트
ruff check src/

Contributing

기여를 환영합니다! 다음 단계를 따라주세요:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

커밋 메시지는 Conventional Commits 형식을 따릅니다.

Related Projects

이 프로젝트는 다음 프로젝트들을 참고하여 개발되었습니다:

• jkf87/hwp-mcp - HWP MCP 서버 원본
• skerishKang/33MCP_HWP_Limone - 고급 HWP MCP 서버

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Hancom - 한글 프로그램 및 오토메이션 API
• Model Context Protocol - MCP 표준
• FastMCP - Python MCP 프레임워크