Skip to main content
Glama
flamingo8006

hwpx-mcp-server

by flamingo8006
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

HWPX MCP Server

npm

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

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/flamingo8006/hwpx-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server