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 지원)

필수 패키지

pip install mcp fastmcp pywin32

🛠️ 설치 및 설정

1. 패키지 설치

# 필수 패키지 설치
pip install -r requirements.txt

# 또는 개별 설치
pip install mcp fastmcp pywin32

2. Claude Desktop 설정

Claude Desktop의 설정 파일에 다음 내용을 추가합니다:

Windows 설정 파일 위치: %APPDATA%\Claude\claude_desktop_config.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 자동 실행 순서:

# 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개의 한글 제어 기능을 제공하며, 실무에서 발생하는 대부분의 문서 편집 문제를 해결할 수 있습니다.