jkf87/hwp-mcp

HWP-MCP는 한글 워드 프로세서(HWP)를 Claude와 같은 AI 모델이 제어할 수 있도록 해주는 Model Context Protocol(MCP) 서버입니다. 이 프로젝트는 한글 문서를 자동으로 생성, 편집, 조작하는 기능을 AI에게 제공합니다.
## 주요 기능
문서 생성 및 관리: 새 문서 생성, 열기, 저장 기능
텍스트 편집: 텍스트 삽입, 글꼴 설정, 단락 추가
테이블 작업: 테이블 생성, 데이터 채우기, 셀 내용 설정
완성된 문서 생성: 템플릿 기반 보고서 및 편지 자동 생성
일괄 작업: 여러 작업을 한 번에 실행하는 배치 기능
## 시스템 요구사항
Windows 운영체제
한글(HWP) 프로그램 설치
Python 3.10 이상 (mcp 패키지 요구사항)
필수 Python 패키지 (requirements.txt 참조)
> macOS/Linux 또는 한글이 설치되지 않은 환경에서도 서버는 실행되며, 이 경우 hwpreadfile(HWP 파일 읽기)만 사용할 수 있습니다.
## 설치 방법
1. 저장소 클론:
bash
git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp
2. 의존성 설치:
bash
pip install -r requirements.txt
3. (선택사항) MCP 패키지 설치:
bash
pip install "mcp<2"
## 사용 방법
### Claude와 함께 사용하기
Claude 데스크톱 설정 파일에 다음과 같이 HWP-MCP 서버를 등록하세요:
json
"mcpServers": {
"hwp": {
"command": "python",
"args": ["경로/hwp-mcp/hwpmcpstdioserver.py"]
### 주요 기능 예시
#### HWP 파일 읽기 (한글 프로그램 불필요, 모든 OS)
python
hwpreadfile("경로/문서.hwp") # 본문 텍스트 반환, 표는 Markdown 표로 변환
#### 새 문서 생성
python
hwpcreate()
#### 텍스트 삽입
python
hwpinserttext("원하는 텍스트를 입력하세요.")
#### 테이블 생성 및 데이터 입력
python
# 테이블 생성
hwpinserttable(rows=5, cols=2)
# 테이블에 데이터 채우기
hwpfilltablewithdata([
["월", "판매량"],
["1월", "120"],
["2월", "150"],
["3월", "180"],
["4월", "200"]
], hasheader=True)
# 표에 연속된 숫자 채우기
hwpfillcolumnnumbers(start=1, end=10, column=1, fromfirstcell=True)
#### 문서 저장
python
hwpsave("경로/문서명.hwp")
#### 일괄 작업 예시
python
hwpbatchoperations([
{"operation": "hwpcreate"},
{"operation": "hwpinserttext", "params": {"text": "제목"}},
{"operation": "hwpsetfont", "params": {"size": 20, "bold": True}},
{"operation": "hwpsave", "params": {"path": "경로/문서명.hwp"}}
])
## 프로젝트 구조
hwp-mcp/
├── hwpmcpstdioserver.py # 메인 서버 스크립트
├── requirements.txt # 의존성 패키지 목록
├── hwp-mcp-구조설명.md # 프로젝트 구조 설명 문서
├── src/
│ ├── tools/
│ │ ├── hwpcontroller.py # 한글 제어 핵심 컨트롤러
│ │ └── hwptabletools.py # 테이블 관련 기능 전문 모듈
│ ├── utils/ # 유틸리티 함수
│ └── tests/ # 테스트 모듈
└── securitymodule/
└── FilePathCheckerModuleExample.dll # 보안 모듈
## 트러블슈팅
### 보안 모듈 관련 문제
기본적으로 한글 프로그램은 외부에서 파일 접근 시 보안 경고를 표시합니다. 이를 우회하기 위해 FilePathCheckerModuleExample.dll 모듈을 사용합니다. 만약 보안 모듈 등록에 실패해도 기능은 작동하지만, 파일 열기/저장 시 보안 대화 상자가 표시될 수 있습니다.
### 한글 연결 실패
한글 프로그램이 실행 중이지 않을 경우 연결에 실패할 수 있습니다. 한글 프로그램이 설치되어 있고 정상 작동하는지 확인하세요.
### 테이블 데이터 입력 문제
테이블에 데이터를 입력할 때 커서 위치가 예상과 다르게 동작하는 경우가 있었으나, 현재 버전에서는 이 문제가 해결되었습니다. 테이블의 모든 셀에 정확하게 데이터가 입력됩니다.
## 변경 로그
### 2025-03-27
표 생성 및 데이터 채우기 기능 개선
표 안에 표가 중첩되는 문제 해결