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

필수 패키지

🛠️ 설치 및 설정

1. 패키지 설치

2. Claude Desktop 설정

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

Windows 설정 파일 위치: %APPDATA%\Claude\claude_desktop_config.json

3. 한글 프로그램 설치 확인

• 한글 프로그램이 설치되어 있어야 합니다

• COM 객체 등록이 정상적으로 되어 있어야 합니다

💡 권장 워크플로우 (중요!)

한글 파일 작업 시 필수 절차

Windows COM의 특성상, 한글 프로그램이 여러 개 실행 중일 때는 하나의 인스턉스에만 연결됩니다. 다음 3단계 워크플로우를 반드시 따라야 안정적으로 작동합니다:

✅ 1단계: 실행 중인 한글 문서 확인

→ list_all_hwp_windows() 호출 → 실행 중인 모든 한글 창과 파일명, 경로 확인

출력 예시:

✅ 2단계: 목표 문서의 전체 경로 확인 및 열기

→ open_document("C:\Users\...\아파트가격동향.hwp") 호출 → MCP 인스턴스가 해당 파일을 열고 제어 가능 상태로 전환 → 자동으로 모든 대화상자 처리 (버전 경고, 접근 권한, 암호 등) → 한글 창이 화면 제일 앞으로 자동 이동

중요:

• 빈 문서를 열지 않고 실제 파일 경로를 사용해야 함

• 파일 경로는 1단계에서 확인한 경로 사용

✅ 3단계: 문서 작업 수행

→ find_and_replace(), get_text_all() 등 사용 → 모든 확인창 자동 승인으로 즉시 실행

📖 실제 사용 예시

사용자: "지금 열려있는 한글 파일 중에 아파트가격동향 문서에서 '경기'를 'GYEONGGI'로 바꿔줘"

Claude 자동 실행 순서:

⚠️ 주의사항

🚀 자동화 기능

모든 확인 대화상자는 자동으로 승인됩니다:

• ✅ 버전 경고 대화상자

• ✅ 파일 접근 권한 확인

• ✅ 암호 입력 건너뛰기

• ✅ 찾기/바꾸기 확인창

• ✅ 삭제 확인창

이 기능은 initialize() 시 자동 활성화되며, 수동 제어도 가능합니다.

🎯 사용 방법

기본 사용법

Claude Desktop에서 다음과 같이 요청하면 됩니다:

고급 사용법

1. 서식이 적용된 문서 생성

2. 표가 포함된 문서

3. 이미지 삽입

4. 페이지 설정

5. 문서 내용 읽기

6. 특정 페이지/문단 읽기

7. 텍스트 파일로 변환

8. 실행 중인 한글에 연결

🆕 고급 분석 및 자동화 기능 사용법

9. 표를 CSV로 추출

10. 여러 텍스트 한번에 바꾸기

11. 텍스트 검색

12. 템플릿 채우기

13. 문서 구조 분석

⭐ 새로운 편집 기능 사용법 (문제 해결!)

14. 정확한 위치에 텍스트 삽입

15. 텍스트 삭제

16. 서식 유지하며 편집

17. 고급 삽입 (특정 텍스트 기준)

18. 문단 단위 편집

🚀 성능 최적화 사용법 (NEW!)

19. 대량 작업 최적화

20. 수동 최적화 제어

21. 자동화 모드 (확인창 자동 승인)

💡 팁: 초기화 시 자동으로 자동화 모드가 활성화되므로, 따로 설정하지 않아도 확인창이 뜨지 않습니다!

📁 프로젝트 구조

🔧 문제해결

1. 한글 초기화 실패

• 한글 프로그램이 설치되어 있는지 확인

• 한글을 한 번 실행해서 정상 동작하는지 확인

• COM 객체 등록 확인

2. 패키지 설치 오류

• 관리자 권한으로 실행

• 가상환경 사용 권장

3. Claude Desktop 연결 실패

• 설정 파일 경로가 정확한지 확인

• Python 경로가 올바른지 확인

• 방화벽 설정 확인

📊 기능 요약 (총 59개 - 24개 신규 추가!)

🚧 알려진 제한사항

1. Windows 전용: 한글 프로그램의 특성상 Windows에서만 동작

2. 한글 필수: 한글 프로그램이 설치되어 있어야 함

3. COM 의존성: Windows COM 객체에 의존

4. 단일 인스턴스 연결: 한글이 여러 개 실행 중일 때 COM은 하나의 프로세스에만 연결됨

   • list_all_hwp_windows()로 어떤 파일이 열려있는지 확인 가능

   • 다른 프로세스의 문서를 제어하려면 open_document()로 해당 파일을 MCP 인스턴스에서 열어야 함

📈 향후 개선 계획

• 텍스트 읽기 기능 추가 (완료)

• 고급 분석 및 자동화 기능 추가 (완료)

• 정밀 위치 제어 및 삭제 기능 추가 (완료) ⭐

• 서식 유지 및 고급 삽입 기능 추가 (완료) ⭐

• 문서 열기 자동화 강화 (대화상자 자동 처리, 창 최상단 표시) (완료) ⭐

• 매크로 실행 기능 추가

• 차트 삽입 기능 추가

• 일괄 서식 적용 기능 강화

• 성능 최적화

• 오류 처리 개선

🤝 기여하기

이 프로젝트는 한국어 문서 작업의 자동화를 위한 프로젝트입니다. 기여, 피드백, 이슈 리포트를 환영합니다!

GitHub: https://github.com/crowwan/hwp-mcp-advanced-custom.git

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

💡 주요 개선사항 (v2.0)

해결된 문제점

1. ✅ 위치 지정 문제 해결

   • 기존: 마우스 커서 위치에만 삽입 가능

   • 개선: 페이지 번호, 문단 번호, 특정 텍스트 기준으로 정확한 위치 제어

2. ✅ 삭제 기능 완전 구현

   • 기존: 삭제 함수 부재

   • 개선: 5가지 삭제 방식 (선택, 패턴, 줄, 문단, 페이지)

3. ✅ 서식 유지 기능 추가

   • 기존: 텍스트만 삽입되어 서식이 깨짐

   • 개선: 현재 서식 조회 및 유지하며 삽입 가능

4. ✅ 고급 삽입 기능

   • 기존: 현재 위치에만 삽입

   • 개선: "제목" 앞/뒤, N번째 문단 끝, 페이지 시작/끝 등 정밀 삽입

5. ✅ 문서 열기 자동화 강화

   • 기존: 대화상자(버전 경고, 접근 권한 등) 수동 처리 필요

   • 개선: 모든 확인 대화상자 자동 승인 + 한글 창 자동으로 화면 최상단 표시

참고: 이 MCP 서버는 총 59개의 한글 제어 기능을 제공하며, 실무에서 발생하는 대부분의 문서 편집 문제를 해결할 수 있습니다.