# Advanced HWP MCP Server
고도화된 한글(HWP) MCP 서버 - 한글의 모든 기능을 제어할 수 있는 MCP 서버입니다.
## 🚀 주요 기능
### 기본 문서 제어
- ✅ 새 문서 생성 (`create_document`)
- ✅ 문서 열기 (`open_document`) - **NEW! 모든 대화상자 자동 처리 + 창 최상단 표시**
- 버전 경고 자동 처리
- 접근 권한 확인 자동 승인
- 암호 입력 자동 건너뛰기
- 한글 창 자동으로 화면 제일 앞에 표시
- ✅ 문서 저장 (`save_document`)
- ✅ 문서 닫기 (`close_document`)
- ✅ 모든 문서 닫기 (`close_all_documents`)
- ✅ 한글 종료 (`quit_hwp`)
- ✅ 문서 정보 조회 (`get_document_info`)
### 실행 중인 한글 연결
- ✅ 열린 문서 목록 조회 (`get_running_hwp_documents`)
- ✅ 실행 중인 한글에 연결 (`connect_to_running_hwp`)
- ✅ 특정 문서로 전환 (`switch_to_document`)
- ✅ 활성 문서 정보 조회 (`get_active_document_info`)
- ✅ 모든 한글 창 목록 조회 (`list_all_hwp_windows`)
- ✅ 특정 한글 창에 연결 (`connect_to_hwp_window`) - 참고: COM 한계로 창 확인용
> ⚠️ **중요**: 한글 파일을 더블클릭으로 여러 개 실행하면 각각 별도의 프로세스로 실행됩니다.
> COM은 하나의 프로세스에만 연결되므로, 다른 프로세스의 문서는 직접 제어할 수 없습니다.
> 아래 "권장 워크플로우" 섹션을 참고하세요.
### 고급 텍스트 조작
- ✅ 정밀한 텍스트 위치 지정 (`insert_text_at_position`)
- ✅ 텍스트 범위 선택 (`select_text_range`)
- ✅ 찾기/바꾸기 (`find_and_replace`)
- ✅ 일반 텍스트 삽입 (`insert_text`)
### 완전한 서식 제어
- ✅ 글꼴 서식 적용 (`apply_font_format`)
- ✅ 문단 서식 설정 (`set_paragraph_format`)
- ✅ 페이지 여백 설정 (`set_page_margins`)
- ✅ 용지 크기 및 방향 설정 (`set_page_size`)
### 표 기능
- ✅ 표 생성 (`create_table`)
- ✅ 셀 병합 (`merge_table_cells`)
### 객체 삽입
- ✅ 이미지 삽입 (`insert_image`)
- ✅ 도형 삽입 (`insert_shape`)
- ✅ 하이퍼링크 삽입 (`insert_hyperlink`)
### 문서 구조 관리
- ✅ 머리글/바닥글 삽입 (`insert_header_footer`)
- ✅ 페이지 나누기 (`insert_page_break`)
- ✅ 목차 생성 (`create_table_of_contents`)
- ✅ 제목 스타일 적용 (`apply_heading_style`)
### 텍스트 읽기 기능
- ✅ 문서 전체 텍스트 읽기 (`get_text_all`)
- ✅ 특정 페이지 텍스트 읽기 (`get_text_by_page`)
- ✅ 선택된 텍스트 읽기 (`get_selected_text`)
- ✅ 특정 문단 텍스트 읽기 (`get_paragraph_text`)
- ✅ 텍스트 파일로 저장 (`save_as_text`)
### 🆕 고급 분석 및 자동화 기능
- ✅ 표를 CSV로 추출 (`get_table_as_csv`) - 특정 표를 CSV 형식으로 추출/저장
- ✅ 일괄 바꾸기 (`batch_replace`) - 여러 텍스트를 한번에 바꾸기
- ✅ 텍스트 검색 (`find_text`) - 텍스트 위치와 주변 내용 검색
- ✅ 템플릿 채우기 (`fill_template`) - 플레이스홀더를 값으로 채우기
- ✅ 문서 구조 분석 (`get_document_structure`) - 페이지/문단/표/이미지/개요 분석
### ⭐ 정밀 위치 제어 (NEW!)
- ✅ 특정 페이지로 이동 (`move_to_page`) - 페이지 번호로 커서 이동
- ✅ 특정 문단으로 이동 (`move_to_paragraph_number`) - 문단 번호로 커서 이동
- ✅ 문서 시작/끝 이동 (`move_to_document_start`, `move_to_document_end`)
### ⭐ 텍스트 삭제 기능 (NEW!)
- ✅ 선택된 텍스트 삭제 (`delete_selected_text`)
- ✅ 특정 텍스트 모두 삭제 (`delete_all_occurrences`)
- ✅ 현재 줄 삭제 (`delete_current_line`)
- ✅ 현재 문단 삭제 (`delete_current_paragraph`)
- ✅ 특정 페이지 내용 삭제 (`delete_page_content`)
### ⭐ 서식 유지 및 조회 (NEW!)
- ✅ 현재 서식 정보 가져오기 (`get_current_char_shape`) - 글꼴, 크기, 색상 등 조회
- ✅ 서식 유지하며 텍스트 삽입 (`insert_text_preserving_format`)
### ⭐ 고급 삽입 기능 (NEW!)
- ✅ 특정 텍스트 뒤에 삽입 (`insert_after_text`) - "제목" 뒤에 추가
- ✅ 특정 텍스트 앞에 삽입 (`insert_before_text`) - "제목" 앞에 추가
- ✅ 문단 끝에 추가 (`append_to_paragraph`) - N번째 문단 끝에
- ✅ 문단 앞에 추가 (`prepend_to_paragraph`) - N번째 문단 앞에
- ✅ 페이지 시작에 삽입 (`insert_at_page_start`)
- ✅ 페이지 끝에 삽입 (`insert_at_page_end`)
### ⭐ 선택 및 교체 (NEW!)
- ✅ 문단 선택 (`select_paragraph_by_number`)
- ✅ 페이지 선택 (`select_page_content`)
- ✅ 문단 내용 교체 (`replace_paragraph`) - 문단 전체를 새 텍스트로
### 🚀 성능 최적화 및 자동화 제어 (NEW!)
- ✅ 화면 업데이트 제어 (`set_screen_updating`) - 대량 작업 시 성능 향상
- ✅ 자동화 모드 제어 (`set_automation_mode`) - 모든 확인창 자동 승인
- ✅ 대량 작업 최적화 (`optimize_for_bulk_operations`) - 최고 성능 모드
- ✅ 일반 모드 복원 (`restore_normal_mode`) - 최적화 해제
### 내보내기 기능
- ✅ PDF 내보내기 (`export_to_pdf`)
- ✅ 한글 초기화 (`initialize_hwp`)
## 📋 필수 요구사항
### 시스템 요구사항
- **운영체제**: Windows (한글 프로그램 지원)
- **Python**: 3.10 이상
- **한글**: 한글 2010 이상 (HWPFrame.HwpObject 지원)
### 필수 패키지
```bash
pip install mcp fastmcp pywin32
```
## 🛠️ 설치 및 설정
### 1. 패키지 설치
```bash
# 필수 패키지 설치
pip install -r requirements.txt
# 또는 개별 설치
pip install mcp fastmcp pywin32
```
### 2. Claude Desktop 설정
Claude Desktop의 설정 파일에 다음 내용을 추가합니다:
**Windows 설정 파일 위치**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"advanced-hwp": {
"command": "python",
"args": [
"D:/mcp/33MCP_HWP_Limone/advanced_hwp_server.py"
],
"env": {
"PYTHONPATH": "D:/mcp/33MCP_HWP_Limone"
}
}
}
}
```
### 3. 한글 프로그램 설치 확인
- 한글 프로그램이 설치되어 있어야 합니다
- COM 객체 등록이 정상적으로 되어 있어야 합니다
## 💡 권장 워크플로우 (중요!)
### 한글 파일 작업 시 필수 절차
Windows COM의 특성상, **한글 프로그램이 여러 개 실행 중일 때는 하나의 인스턉스에만 연결**됩니다.
다음 3단계 워크플로우를 **반드시 따라야** 안정적으로 작동합니다:
#### ✅ 1단계: 실행 중인 한글 문서 확인
```
"현재 열려있는 한글 파일 목록을 보여줘"
```
→ `list_all_hwp_windows()` 호출
→ 실행 중인 모든 한글 창과 파일명, 경로 확인
**출력 예시**:
```
실행 중인 한글 창 (2개):
[0] !220324(보도자료)_주간아파트가격동향.hwp [C:\Users\...\Downloads\]
PID: 27380, HWND: 12345
[1] 회의록.hwp [D:\Documents\] - 한글
PID: 28901, HWND: 67890
```
#### ✅ 2단계: 목표 문서의 전체 경로 확인 및 열기
```
"아파트가격동향 파일을 열어줘"
```
→ `open_document("C:\Users\...\아파트가격동향.hwp")` 호출
→ MCP 인스턴스가 해당 파일을 열고 제어 가능 상태로 전환
→ **자동으로 모든 대화상자 처리** (버전 경고, 접근 권한, 암호 등)
→ **한글 창이 화면 제일 앞으로** 자동 이동
**중요**:
- 빈 문서를 열지 않고 **실제 파일 경로**를 사용해야 함
- 파일 경로는 1단계에서 확인한 경로 사용
#### ✅ 3단계: 문서 작업 수행
```
"'경기(-0.03%)'를 '[TEMP_GYEONGGI]'로 바꿔줘"
"문서 전체 내용을 읽어줘"
```
→ `find_and_replace()`, `get_text_all()` 등 사용
→ 모든 확인창 자동 승인으로 즉시 실행
### 📖 실제 사용 예시
**사용자**: "지금 열려있는 한글 파일 중에 아파트가격동향 문서에서 '경기'를 'GYEONGGI'로 바꿔줘"
**Claude 자동 실행 순서**:
```python
# 1단계
list_all_hwp_windows()
# → 출력: "!220324(보도자료)_주간아파트가격동향.hwp [C:\Users\LENOVO\Downloads\]"
# 2단계
open_document("C:\\Users\\LENOVO\\Downloads\\!220324(보도자료)_주간아파트가격동향.hwp")
# → "문서를 열었습니다" + 한글 창 최상단 표시
# 3단계
find_and_replace("경기", "GYEONGGI")
# → 자동으로 모든 '경기' 텍스트 바꾸기 (확인창 없음)
```
### ⚠️ 주의사항
| 상황 | 동작 방식 | 해결 방법 |
|------|----------|-----------|
| **한글 1개 실행 중** | MCP가 해당 인스턴스에 연결되어 모든 문서 제어 가능 | 정상 작동 |
| **한글 여러 개 실행 중** | MCP는 하나의 인스턴스에만 연결됨 | 1단계로 확인 후 `open_document()`로 필요한 파일 열기 |
| **한글 실행 안 됨** | `initialize_hwp()` 호출 시 자동으로 새 한글 실행 | 정상 작동 |
| **빈 문서만 열림** | ❌ 잘못된 접근 - 실제 파일이 아닌 빈 문서 제어 중 | 반드시 1-2단계 거쳐서 실제 파일 경로로 열기 |
### 🚀 자동화 기능
모든 확인 대화상자는 **자동으로 승인**됩니다:
- ✅ 버전 경고 대화상자
- ✅ 파일 접근 권한 확인
- ✅ 암호 입력 건너뛰기
- ✅ 찾기/바꾸기 확인창
- ✅ 삭제 확인창
이 기능은 `initialize()` 시 자동 활성화되며, 수동 제어도 가능합니다.
## 🎯 사용 방법
### 기본 사용법
Claude Desktop에서 다음과 같이 요청하면 됩니다:
```
새 한글 문서를 만들고 "안녕하세요"라는 텍스트를 삽입해주세요.
```
### 고급 사용법
#### 1. 서식이 적용된 문서 생성
```
새 문서를 만들고 제목을 "보고서"로 하되 맑은고딕 18pt 굵게 설정하고,
본문에 "내용입니다"를 바탕 12pt로 추가해주세요.
```
#### 2. 표가 포함된 문서
```
3행 4열 표를 만들고 첫 번째 행의 셀들을 병합해주세요.
```
#### 3. 이미지 삽입
```
C:\images\logo.png 이미지를 문서에 삽입하고 크기를 100x50mm로 설정해주세요.
```
#### 4. 페이지 설정
```
A4 용지를 가로 방향으로 설정하고 여백을 상하좌우 15mm로 설정해주세요.
```
#### 5. 문서 내용 읽기
```
이 한글 문서를 열고 전체 내용을 읽어주세요.
```
#### 6. 특정 페이지/문단 읽기
```
문서의 2페이지 내용만 읽어주세요.
첫 번째 문단의 내용을 확인해주세요.
```
#### 7. 텍스트 파일로 변환
```
이 한글 문서를 텍스트 파일로 저장해주세요.
```
#### 8. 실행 중인 한글에 연결
```
현재 열려있는 한글 문서 목록을 보여주세요.
아파트 가격 문서로 전환해주세요.
```
### 🆕 고급 분석 및 자동화 기능 사용법
#### 9. 표를 CSV로 추출
```
문서의 첫 번째 표를 CSV로 추출해줘
두 번째 표를 C:\output\table.csv로 저장해줘
```
#### 10. 여러 텍스트 한번에 바꾸기
```
다음 텍스트들을 한번에 바꿔줘: 주식회사->㈜, 2023년->2024년, 홍길동->김철수
```
#### 11. 텍스트 검색
```
문서에서 "세종"이 어디에 있는지 찾아줘
"아파트"라는 단어가 몇 번 나오는지 확인해줘
```
#### 12. 템플릿 채우기
```
문서의 {{이름}}을 홍길동으로, {{날짜}}를 2024-01-01로, {{금액}}을 1,000,000원으로 채워줘
```
#### 13. 문서 구조 분석
```
이 문서의 전체 구조를 분석해줘
문서에 표가 몇 개 있고 어떤 내용인지 알려줘
```
### ⭐ 새로운 편집 기능 사용법 (문제 해결!)
#### 14. 정확한 위치에 텍스트 삽입
```
3페이지로 이동해서 "새로운 내용"을 추가해줘
"서론" 뒤에 "이 문서는..."을 추가해줘
첫 번째 문단 끝에 "추가 설명"을 넣어줘
```
#### 15. 텍스트 삭제
```
"초안"이라는 단어를 모두 삭제해줘
현재 문단을 삭제해줘
2페이지의 모든 내용을 지워줘
```
#### 16. 서식 유지하며 편집
```
현재 위치의 서식 정보를 알려줘
서식을 유지하면서 "중요 내용"을 삽입해줘
```
#### 17. 고급 삽입 (특정 텍스트 기준)
```
"1. 서론" 뒤에 줄바꿈하고 본문을 추가해줘
"제목" 앞에 "최종본 - "을 붙여줘
두 번째 "결론" 뒤에 추가 설명을 넣어줘 (nth_occurrence 사용)
```
#### 18. 문단 단위 편집
```
0번째 문단을 "새로운 제목"으로 교체해줘
1번째 문단을 선택하고 서식을 적용해줘
2번째 문단 앞에 "중요: "를 추가해줘
```
### 🚀 성능 최적화 사용법 (NEW!)
#### 19. 대량 작업 최적화
```
대량 작업 최적화 모드를 켜줘
(1000개 텍스트를 일괄 바꾸기)
일반 모드로 복원해줘
```
#### 20. 수동 최적화 제어
```
화면 업데이트를 꺼줘 (성능 향상)
(작업 수행)
화면 업데이트를 켜줘 (정상 속도)
```
#### 21. 자동화 모드 (확인창 자동 승인)
```
자동화 모드를 켜줘 (모든 확인창 자동 Yes)
(바꾸기, 삭제 등 작업 - 확인창 없이 즉시 실행)
```
**💡 팁**: 초기화 시 자동으로 자동화 모드가 활성화되므로, 따로 설정하지 않아도 확인창이 뜨지 않습니다!
## 📁 프로젝트 구조
```
33MCP_HWP_Limone/
├── advanced_hwp_server.py # 메인 MCP 서버
├── requirements.txt # 필수 패키지 목록
├── claude_desktop_config.json # Claude Desktop 설정 예시
├── README.md # 이 파일
├── INSTALLATION_GUIDE.md # 설치 가이드
└── hwp_mcp.log # 실행 로그
```
## 🔧 문제해결
### 1. 한글 초기화 실패
```
한글 프로그램이 설치되지 않았거나 초기화할 수 없습니다.
```
- 한글 프로그램이 설치되어 있는지 확인
- 한글을 한 번 실행해서 정상 동작하는지 확인
- COM 객체 등록 확인
### 2. 패키지 설치 오류
```
pip install pywin32
```
- 관리자 권한으로 실행
- 가상환경 사용 권장
### 3. Claude Desktop 연결 실패
- 설정 파일 경로가 정확한지 확인
- Python 경로가 올바른지 확인
- 방화벽 설정 확인
## 📊 기능 요약 (총 59개 - 24개 신규 추가!)
| 카테고리 | 기능 수 | 주요 기능 |
|----------|---------|-----------|
| 기본 문서 제어 | 7개 | 생성, 열기, 저장, 닫기, 종료 |
| 한글 연결 | 6개 | 실행 중 한글 연결, 창 목록, 문서 전환 |
| 텍스트 조작 | 4개 | 삽입, 선택, 찾기/바꾸기 |
| 서식 제어 | 4개 | 글꼴, 문단, 페이지 여백, 용지 |
| 표 기능 | 2개 | 생성, 셀 병합 |
| 객체 삽입 | 3개 | 이미지, 도형, 하이퍼링크 |
| 문서 구조 | 4개 | 머리글/바닥글, 페이지 나누기, 목차, 제목 |
| 텍스트 읽기 | 5개 | 전체, 페이지별, 선택, 문단별, 텍스트 저장 |
| 고급 자동화 | 5개 | CSV 추출, 일괄 바꾸기, 검색, 템플릿, 구조 분석 |
| **⭐ 정밀 위치 제어** | **4개 (NEW)** | **페이지/문단 이동, 시작/끝 이동** |
| **⭐ 텍스트 삭제** | **5개 (NEW)** | **선택 삭제, 패턴 삭제, 줄/문단/페이지 삭제** |
| **⭐ 서식 유지** | **2개 (NEW)** | **서식 조회, 서식 유지 삽입** |
| **⭐ 고급 삽입** | **6개 (NEW)** | **텍스트 앞/뒤 삽입, 문단/페이지 위치 삽입** |
| **⭐ 선택 및 교체** | **3개 (NEW)** | **문단/페이지 선택, 문단 교체** |
| **🚀 성능 최적화** | **4개 (NEW)** | **화면 업데이트, 자동화 모드, 대량 작업 최적화** |
| 내보내기 | 2개 | PDF, 초기화 |
## 🚧 알려진 제한사항
1. **Windows 전용**: 한글 프로그램의 특성상 Windows에서만 동작
2. **한글 필수**: 한글 프로그램이 설치되어 있어야 함
3. **COM 의존성**: Windows COM 객체에 의존
4. **단일 인스턴스 연결**: 한글이 여러 개 실행 중일 때 COM은 하나의 프로세스에만 연결됨
- `list_all_hwp_windows()`로 어떤 파일이 열려있는지 확인 가능
- 다른 프로세스의 문서를 제어하려면 `open_document()`로 해당 파일을 MCP 인스턴스에서 열어야 함
## 📈 향후 개선 계획
- [x] 텍스트 읽기 기능 추가 (완료)
- [x] 고급 분석 및 자동화 기능 추가 (완료)
- [x] **정밀 위치 제어 및 삭제 기능 추가 (완료)** ⭐
- [x] **서식 유지 및 고급 삽입 기능 추가 (완료)** ⭐
- [x] **문서 열기 자동화 강화 (대화상자 자동 처리, 창 최상단 표시) (완료)** ⭐
- [ ] 매크로 실행 기능 추가
- [ ] 차트 삽입 기능 추가
- [ ] 일괄 서식 적용 기능 강화
- [ ] 성능 최적화
- [ ] 오류 처리 개선
## 🤝 기여하기
이 프로젝트는 한국어 문서 작업의 자동화를 위한 프로젝트입니다.
기여, 피드백, 이슈 리포트를 환영합니다!
**GitHub**: https://github.com/crowwan/hwp-mcp-advanced-custom.git
## 📄 라이선스
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
---
## 💡 주요 개선사항 (v2.0)
### 해결된 문제점
1. **✅ 위치 지정 문제 해결**
- 기존: 마우스 커서 위치에만 삽입 가능
- 개선: 페이지 번호, 문단 번호, 특정 텍스트 기준으로 정확한 위치 제어
2. **✅ 삭제 기능 완전 구현**
- 기존: 삭제 함수 부재
- 개선: 5가지 삭제 방식 (선택, 패턴, 줄, 문단, 페이지)
3. **✅ 서식 유지 기능 추가**
- 기존: 텍스트만 삽입되어 서식이 깨짐
- 개선: 현재 서식 조회 및 유지하며 삽입 가능
4. **✅ 고급 삽입 기능**
- 기존: 현재 위치에만 삽입
- 개선: "제목" 앞/뒤, N번째 문단 끝, 페이지 시작/끝 등 정밀 삽입
5. **✅ 문서 열기 자동화 강화**
- 기존: 대화상자(버전 경고, 접근 권한 등) 수동 처리 필요
- 개선: 모든 확인 대화상자 자동 승인 + 한글 창 자동으로 화면 최상단 표시
---
**참고**: 이 MCP 서버는 총 **59개의 한글 제어 기능**을 제공하며, 실무에서 발생하는 대부분의 문서 편집 문제를 해결할 수 있습니다.
