HWPX MCP Server

AI 도구(Claude, Cursor 등)와 연동하여 한글(HWPX) 문서를 자동으로 편집할 수 있는 MCP(Model Context Protocol) 서버입니다. 132개 도구를 제공합니다.

---

Cross-Platform Support

OS	MCP 서버	HWPX 편집	결과물 확인
Windows	O	O	한컴오피스
macOS	O	O	한컴오피스 Mac
Linux	O	O	한컴오피스 Linux / LibreOffice*

HWPX 파일은 ZIP + XML 구조이므로 한글 프로그램 없이도 Node.js만으로 읽고 쓸 수 있습니다. *LibreOffice는 HWPX를 제한적으로 지원합니다.

---

1. 설정

별도 설치 없이 MCP 클라이언트 설정만 추가하면 됩니다. (Node.js 18+ 필요)

Claude Desktop

설정 파일 위치:

OS	경로
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

설정 내용:

{
  "mcpServers": {
    "hwpx": {
      "command": "npx",
      "args": ["-y", "hwpx-mcp-server@latest"]
    }
  }
}

---

Claude Code (CLI)

macOS / Linux:

# 전역 설정 (모든 프로젝트에서 사용)
claude mcp add hwpx --scope user npx -y hwpx-mcp-server@latest

# 프로젝트별 설정
claude mcp add hwpx npx -y hwpx-mcp-server@latest

Windows:

# 전역 설정
claude mcp add hwpx --scope user -- npx -y hwpx-mcp-server@latest

# 프로젝트별 설정
claude mcp add hwpx -- npx -y hwpx-mcp-server@latest

Windows에서는 --를 넣어야 -y 옵션이 정상 전달됩니다.

---

Cursor

설정 파일: ~/.cursor/mcp.json

{
  "mcpServers": {
    "hwpx": {
      "command": "npx",
      "args": ["-y", "hwpx-mcp-server@latest"]
    }
  }
}

---

VS Code

설정 파일: .vscode/mcp.json

{
  "servers": {
    "hwpx": {
      "command": "npx",
      "args": ["-y", "hwpx-mcp-server@latest"]
    }
  }
}

---

Codex / Gemini CLI / 기타

{
  "mcpServers": {
    "hwpx": {
      "command": "npx",
      "args": ["-y", "hwpx-mcp-server@latest"]
    }
  }
}

---

2. 문서 작성 스킬 설치 (선택)

스킬 파일을 설치하면 AI가 build_document 도구를 활용하여 서식이 갖춰진 한글 문서를 한 번의 호출로 작성합니다.

스킬 파일 URL: https://raw.githubusercontent.com/flamingo8006/hwpx-mcp/main/skills/hwpx-document-writer.md

Claude Code

macOS / Linux:

mkdir -p ~/.claude/skills/hwpx-document-writer
curl -o ~/.claude/skills/hwpx-document-writer/skill.md \
  https://raw.githubusercontent.com/flamingo8006/hwpx-mcp/main/skills/hwpx-document-writer.md

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\hwpx-document-writer"
curl.exe -o "$HOME\.claude\skills\hwpx-document-writer\skill.md" `
  https://raw.githubusercontent.com/flamingo8006/hwpx-mcp/main/skills/hwpx-document-writer.md

Claude Desktop

Claude Desktop은 공식적으로 커스텀 스킬을 지원하지 않습니다. 프로젝트 Custom Instructions 사용을 권장합니다:

1. 위 URL에서 스킬 파일 내용을 복사
2. Claude Desktop에서 프로젝트 생성
3. 프로젝트 설정 → Custom Instructions 에 붙여넣기

기타 클라이언트 (Cursor / Codex / Gemini CLI)

위 URL에서 스킬 파일 내용을 복사하여 시스템 프롬프트에 포함시키면 동일한 효과를 얻을 수 있습니다.

---

3. 설치 확인

클라이언트 재시작 후 MCP 도구 목록에서 hwpx 서버와 132개 도구가 표시되면 성공입니다.

---

4. MCP 도구 목록 (132개)

문서 관리 (8개)

도구	설명
get_tool_guide	도구 사용 가이드 조회
create_document	새 빈 HWPX 문서 생성
open_document	HWPX 문서 열기
close_document	열린 문서 닫기
save_document	문서 저장 (백업/무결성 검증 지원)
list_open_documents	현재 열린 문서 목록
get_document_metadata	메타데이터 조회 (제목, 저자, 날짜)
set_document_metadata	메타데이터 수정

문서 조회 (9개)

도구	설명
get_document_text	전체 텍스트 추출
get_document_structure	문서 구조 (섹션/단락/테이블/이미지 수)
get_document_outline	문서 개요 (제목 기반)
get_paragraphs	단락 목록 조회
get_paragraph	특정 단락 상세 정보
get_word_count	글자수/단어수 통계
get_insert_context	삽입 위치 컨텍스트 조회
find_insert_position_after_header	제목 다음 삽입 위치 찾기
find_insert_position_after_table	테이블 다음 삽입 위치 찾기

텍스트 편집 (11개)

도구	설명
insert_paragraph	새 단락 삽입
update_paragraph_text	단락 텍스트 수정 (전체 교체)
update_paragraph_text_preserve_styles	스타일 유지하며 텍스트 수정
append_text_to_paragraph	기존 단락에 텍스트 추가
delete_paragraph	단락 삭제
copy_paragraph	단락 복사
move_paragraph	단락 이동
format_text	텍스트 포매팅
search_text	텍스트 검색 (정규식, 테이블 셀 포함)
replace_text	텍스트 찾아 바꾸기
find_paragraph_by_text	텍스트로 단락 찾기

일괄 처리 (2개)

도구	설명
batch_replace	여러 텍스트 일괄 치환
batch_fill_table	테이블 여러 셀 일괄 채우기

서식 - 문자/문단 스타일 (10개)

도구	설명
get_text_style	문자 스타일 조회 (폰트/크기/색상)
set_text_style	문자 스타일 설정
get_paragraph_style	문단 스타일 조회 (정렬/줄간격/여백)
set_paragraph_style	문단 스타일 설정
get_styles	문서 스타일 목록
get_char_shapes	문자 모양(CharShape) 정의
get_para_shapes	문단 모양(ParaShape) 정의
apply_style	단락에 스타일 적용
get_column_def	단(Column) 설정 조회
set_column_def	단 설정 변경 (다단 편집)

번호/불릿 매기기 (3개)

도구	설명
get_numbering_defs	번호 매기기 정의 목록
get_bullet_defs	불릿 정의 목록
set_numbering	번호/불릿 목록 스타일 적용

내어쓰기 (8개)

도구	설명
get_hanging_indent	내어쓰기 조회
set_hanging_indent	내어쓰기 설정
set_auto_hanging_indent	자동 내어쓰기
remove_hanging_indent	내어쓰기 제거
get_table_cell_hanging_indent	셀 내어쓰기 조회
set_table_cell_hanging_indent	셀 내어쓰기 설정
set_table_cell_auto_hanging_indent	셀 자동 내어쓰기
remove_table_cell_hanging_indent	셀 내어쓰기 제거

테이블 (29개)

도구	설명
get_tables	테이블 목록
get_table	테이블 상세 데이터
get_table_cell	특정 셀 내용
get_table_as_csv	테이블을 CSV로 추출
get_table_map	테이블 구조 맵
get_tables_summary	테이블 요약 정보
get_tables_by_section	섹션별 테이블
get_cell_context	셀 컨텍스트 정보
find_table_by_header	헤더로 테이블 찾기
find_cell_by_label	라벨로 셀 찾기
find_empty_tables	빈 테이블 찾기
get_element_index_for_table	테이블 요소 인덱스
fill_by_path	경로 기반 셀 채우기
insert_table	테이블 삽입
insert_nested_table	중첩 테이블 삽입 (표 안에 표)
delete_table	테이블 삭제
update_table_cell	셀 수정
replace_text_in_cell	셀 내 텍스트 치환
set_cell_properties	셀 속성 설정 (크기/배경/정렬)
set_cell_background_color	셀 배경색 설정
set_column_widths	열 너비 설정
insert_table_row	행 추가
delete_table_row	행 삭제
insert_table_column	열 추가
delete_table_column	열 삭제
merge_cells	셀 병합
split_cell	셀 분할
copy_table	테이블 복사
move_table	테이블 이동

이미지 (7개)

도구	설명
get_images	이미지 목록
insert_image	이미지 삽입
insert_image_in_cell	테이블 셀에 이미지 삽입
update_image_size	이미지 크기 변경
delete_image	이미지 삭제
render_mermaid	Mermaid 다이어그램 삽입
render_mermaid_in_cell	셀에 Mermaid 다이어그램 삽입

도형 (3개)

도구	설명
insert_line	선 도형 삽입
insert_rect	사각형 도형 삽입
insert_ellipse	타원 도형 삽입

머리글/바닥글 (4개)

도구	설명
get_header	머리글 조회
set_header	머리글 설정
get_footer	바닥글 조회
set_footer	바닥글 설정

각주/미주 (4개)

도구	설명
get_footnotes	각주 목록
insert_footnote	각주 삽입
get_endnotes	미주 목록
insert_endnote	미주 삽입

북마크/하이퍼링크 (4개)

도구	설명
get_bookmarks	북마크 목록
insert_bookmark	북마크 삽입
get_hyperlinks	하이퍼링크 목록
insert_hyperlink	하이퍼링크 삽입

수식/메모 (5개)

도구	설명
get_equations	수식 목록
insert_equation	수식 삽입
get_memos	메모 목록
insert_memo	메모 삽입
delete_memo	메모 삭제

섹션/페이지 (6개)

도구	설명
get_sections	섹션 목록
insert_section	섹션 삽입
delete_section	섹션 삭제
get_page_settings	페이지 설정 조회
set_page_settings	페이지 설정 변경
insert_page_break	페이지 나누기 삽입

내보내기 (2개)

도구	설명
export_to_text	텍스트 파일로 내보내기
export_to_html	HTML 파일로 내보내기

실행 취소 (2개)

도구	설명
undo	실행 취소
redo	다시 실행

검색/인덱싱 (8개)

도구	설명
chunk_document	문서 청킹
search_chunks	청크 검색
get_chunk_context	청크 컨텍스트
get_chunk_at_offset	오프셋 청크 조회
extract_toc	목차 추출
build_position_index	위치 인덱스 빌드
get_position_index	위치 인덱스 조회
search_position_index	위치 인덱스 검색

고급/디버깅 (7개)

도구	설명
get_section_xml	섹션 XML 조회
set_section_xml	섹션 XML 설정
get_raw_section_xml	원본 섹션 XML 조회
set_raw_section_xml	원본 섹션 XML 설정
analyze_xml	XML 구조 분석
repair_xml	XML 복구
invalidate_reading_cache	읽기 캐시 무효화

---

5. 사용 예시

예시 1: 기본 문서 편집

사용자: report.hwpx 열어서 3번째 단락 텍스트를 수정해줘

AI 동작:
1. open_document("report.hwpx")
2. get_paragraphs(section_index=0) → 단락 목록 확인
3. update_paragraph_text(section=0, paragraph=2, text="수정된 내용")
4. save_document()

예시 2: 테이블 셀 수정

사용자: 사업계획서.hwpx에서 3번째 테이블의 2행 1열을 수정해줘

AI 동작:
1. open_document("사업계획서.hwpx")
2. get_tables() → 테이블 목록 확인
3. get_table(section=0, index=2) → 구조 확인
4. update_table_cell(section=0, table=2, row=1, col=0, text="수정 내용")
5. save_document()

예시 3: 스타일 복사 후 새 단락 추가

사용자: 기존 양식의 스타일을 참고해서 새 문단을 추가해줘

AI 동작:
1. get_paragraph_style(sec=0, para=10) → {align: "Justify", lineSpacing: 145}
2. get_text_style(sec=0, para=10) → {fontName: "맑은 고딕", fontSize: 14}
3. insert_paragraph(sec=0, after=10, text="새 내용")
4. set_paragraph_style(sec=0, para=11, align="justify", line_spacing=145)
5. set_text_style(sec=0, para=11, font_name="맑은 고딕", font_size=14)
6. save_document()

예시 4: 테이블 셀 검색 후 정밀 치환

사용자: "김철수"를 "이영희"로 바꿔줘 (3번째 테이블의 것만)

AI 동작:
1. search_text(query="김철수", include_tables=true)
   → [{type: "table", tableIndex: 2, row: 3, col: 1}, ...]
2. replace_text_in_cell(table=2, row=3, col=1, old="김철수", new="이영희")
3. save_document()

예시 5: Mermaid 다이어그램 삽입

사용자: 플로우차트를 문서에 넣어줘

AI 동작:
1. render_mermaid(
     mermaid_code="graph TD; A[시작]-->B[처리]; B-->C[완료]",
     after_index=5,
     theme="default"
   )
2. save_document()

예시 6: 일괄 치환

사용자: "2025년"을 "2026년"으로, "홍길동"을 "김영수"로 전부 바꿔줘

AI 동작:
1. batch_replace(replacements=[
     {old_text: "2025년", new_text: "2026년"},
     {old_text: "홍길동", new_text: "김영수"}
   ])
2. save_document()

---

6. 지원 포맷

포맷	확장자	읽기	쓰기
HWPX	.hwpx	O	O
HWP	.hwp	X	X

HWP(바이너리) 파일은 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.

---

7. 알려진 제한사항

• 각주/미주/북마크/하이퍼링크 삽입: 메모리에서만 동작, save 후 XML 미반영 (읽기는 정상)
• HWP 파일: 지원하지 않음 (HWPX로 변환 필요)
• secPr 문단 스타일: 첫 번째 특수 문단에서 스타일 reload 제한

---

8. 개발

빌드

cd mcp-server
npm run build

테스트

cd mcp-server
npm test                          # 전체 테스트 (vitest)
npx vitest run src/HwpxDocument.test.ts  # 특정 파일
npx vitest run -t "test name"     # 이름 패턴

---

Credits

• Original Project: mjyoo2/hwp-extension
• Enhanced by: Dayoooun

License

MIT