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