hwp-edit-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hwp-edit-mcp 보고서.hwpx 표에서 '담당자' 라벨 옆 칸에 김민수 채워줘"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hwp-edit-mcp
AI 에이전트가 HWP·HWPX 문서를 고칠 때 원본을 지키는 안전한 쓰기(해시 충돌 검사, 자동 스냅샷, 재열기 검증, 원자 교체), 라벨 기반 표 채우기, 히스토리·복원·비교를 제공하는 MCP 서버입니다.
빠른 시작
uvx hwp-edit-mcp첫 실행 시 rhwp 실행 파일을 캐시에 자동으로 내려받습니다. Claude Code 등록 예:
claude mcp add -s user hwp -- uvx hwp-edit-mcp다른 에이전트(Claude Desktop, Codex, Grok CLI, Antigravity, Gemini CLI, OpenCode, Cursor, VS Code) 설정은 에이전트별 설정 안내, 문제 해결은 트러블슈팅을 참고하세요.
Related MCP server: HWPX MCP Server
안전한 쓰기(SafeWriter)
모든 쓰기 도구는 SafeWriter 트랜잭션을 거칩니다.
해시 충돌 검사: 직전에 읽은 SHA-256 또는
expected_sha256과 현재 파일 해시를 대조해 외부 편집기 수정과의 충돌을 막습니다(force=True로 우회 가능).자동 스냅샷: 수정 직전 원본을 문서 폴더의
.hwp-mcp-history/<파일명>/에 최대 50개까지 보관합니다.임시 파일 격리 및 재열기 검증: 같은 폴더의 임시 파일에 먼저 쓴 뒤 손실 보고(
lossCount)가 없는지 확인하고,rhwp로 다시 열어 페이지 수 급감이나 파손을 검사합니다(allow_loss=True로 허용 가능).원자 교체:
os.replace로 원본을 교체하며, Windows 파일 잠금(PermissionError) 시 짧게 대기하며 재시도합니다.
제공 도구 (14개)
이름 | 하는 일 | 구분 |
| 문서 메타데이터(형식, 페이지 수, 문단 수, 글꼴, SHA-256) 조회 | 읽기 |
| 본문 텍스트 추출 ( | 읽기 |
| 문자열 검색 및 페이지·문맥·표 셀 좌표 반환 | 읽기 |
| 표 크기, 병합 정보, 셀 좌표·텍스트 조회 ( | 읽기 |
| 좌표( | 쓰기 |
| 본문·표 셀 텍스트 일괄 치환 | 쓰기 |
| 누름틀(필드) 이름 기준 값 채우기 | 쓰기 |
| 지정한 섹션·문단·오프셋 위치에 텍스트 삽입 | 쓰기 |
| rhwp 선언적 편집 계획서(plan JSON) 일괄 실행 | 쓰기 |
| 페이지를 PNG 또는 SVG 이미지로 렌더링 | 읽기 |
|
| 읽기 |
|
| 쓰기 |
| 두 파일 또는 현재 문서와 스냅샷 간 텍스트 unified diff 비교 | 읽기 |
| rhwp 내장 180여 개 도구 직접 호출 (쓰기 도구는 SafeWriter 경유) | 읽기/쓰기 |
CLI 옵션 및 환경변수
CLI 옵션 | 환경변수 | 기본값 | 설명 |
|
| 비활성 | 쓰기 도구를 등록하지 않고 읽기·검사 도구만 노출 |
|
| 제한 없음 | 접근 허용 폴더 지정 (Windows |
|
| 자동 탐색/다운로드 | 사용할 |
| — | — |
|
— |
|
| 도구 응답 최대 문자 수 상한 |
— |
| 비활성 |
|
— |
| OS 기본 캐시 |
|
— |
| stderr만 출력 | 서버 로그를 파일에도 기록 |
rhwp와의 관계
rhwp는 mcp-serve 명령으로 저수준 HWP/HWPX 파싱·편집 도구를 제공합니다. hwp-edit-mcp는 rhwp mcp-serve를 상주 하위 프로세스로 감싸면서, 에이전트 실수나 덮어쓰기로부터 문서를 보호하는 SafeWriter(해시 충돌 검사, 스냅샷 백업·복원·diff, 재열기 무손실 검증, 원자 교체), 라벨 기반 표 셀 채우기, 허용 폴더(--root) 및 읽기 전용(--read-only) 가드, 응답 길이 제한(max_chars), 자동 rhwp 설치·캐싱을 더합니다.
감사의 말
jkf87/hwp-mcp를 포크해 시작했고, rhwp 엔진 기반으로 다시 작성했습니다.
라이선스
hwp-edit-mcp는 MIT License로 배포됩니다. 런타임에 사용하는 rhwp의 MIT 라이선스 고지는 NOTICE를 확인하세요.
Available Tools
14 toolshwp_diff문서 텍스트 비교ARead-only
두 문서 파일(file_path_a vs file_path_b) 또는 현재 문서와 스냅샷(snapshot_id) 간의 텍스트 unified diff 를 반환합니다. file_path_a는 절대 경로 권장.
Inputs: file_path_a (required), password, file_path_b, snapshot_id.
hwp_fill_cells표 셀 채우기ADestructive
표의 셀 값을 일괄 채웁니다. 각 항목은 좌표 기준({'row': 0, 'col': 1, 'text': '값'}) 또는 라벨 기준({'label': '성명', 'text': '홍길동', 'direction': 'right'|'below'})을 지원합니다. 라벨 기준에서 표 번호('table' 또는 table_index)를 생략하면 모든 표를 앞에서부터 찾아 첫 일치를 씁니다. 좌표 기준에서 표 번호를 생략하면 0번 표입니다. SafeWriter를 통해 스냅샷 백업 및 무손실 검증 후 원자 교체합니다. file_path는 절대 경로 권장.
Inputs: cells (required), file_path (required), force, password, +3 more.
hwp_fill_fields누름틀 필드 채우기CDestructive
문서 내 누름틀(필드) 값을 이름 기준으로 채웁니다. SafeWriter를 경유합니다. file_path는 절대 경로 권장.
Inputs: data (required), file_path (required), force, password, +2 more.
hwp_get_text문서 본문 추출BRead-only
HWP/HWPX 문서의 본문 텍스트를 추출합니다. format='text' 또는 'markdown'을 지원합니다. file_path는 절대 경로 권장.
Inputs: file_path (required), page, format, password, +1 more.
hwp_history스냅샷 히스토리 조회ARead-only
문서의 SafeWriter 스냅샷 히스토리(.hwp-mcp-history) 목록을 최신순으로 조회합니다. file_path는 절대 경로 권장.
Inputs: file_path (required).
hwp_info문서 정보 조회BRead-only
HWP/HWPX 문서의 메타데이터(형식, 페이지 수, 문단 수, 글꼴, SHA-256 해시 등)를 조회합니다. file_path는 절대 경로 권장.
Inputs: file_path (required), password.
hwp_insert_text텍스트 삽입CDestructive
지정한 섹션/문단/문자 오프셋 위치에 텍스트를 삽입합니다. SafeWriter를 경유합니다. file_path는 절대 경로 권장.
Inputs: text (required), file_path (required), force, offset, +4 more.
hwp_render_page페이지 이미지 렌더링A
문서 페이지를 PNG 또는 SVG 이미지 파일로 렌더링하여 저장 경로를 반환합니다(시각 확인용). page는 0부터 시작하며, -1이면 전체 페이지를 렌더합니다. file_path는 절대 경로 권장.
Inputs: file_path (required), page, format, output_dir.
hwp_replace_text텍스트 일괄 치환CDestructive
문서 본문 및 표 셀 내의 텍스트를 찾아 일괄 치환합니다. SafeWriter를 경유합니다. file_path는 절대 경로 권장.
Inputs: find (required), replace (required), file_path (required), force, +3 more.
hwp_restore스냅샷 복원ADestructive
hwp_history에서 확인한 snapshot_id 로 문서를 복원합니다. 복원 전 현재 파일도 스냅샷으로 백업한 뒤 원자 교체합니다. file_path는 절대 경로 권장.
Inputs: file_path (required), snapshot_id (required), force, expected_sha256.
hwp_rhwp_callrhwp 도구 직접 호출BDestructive
rhwp 가 제공하는 180여 개 전체 도구 중 하나를 직접 호출하는 탈출구입니다. output 인자를 받는 쓰기 도구는 SafeWriter를 경유해 임시 파일 출력·검증·원자 교체를 수행합니다. file_path는 절대 경로 권장.
Inputs: file_path (required), tool_name (required), force, is_write, +3 more.
hwp_run_plan편집 계획 실행BDestructive
rhwp 선언적 편집 계획서(plan JSON)를 일괄 실행합니다. input/output 경로는 SafeWriter가 안전하게 바인딩합니다. file_path는 절대 경로 권장.
Inputs: plan (required), file_path (required), force, allow_loss, +1 more.
hwp_search문서 문자열 검색CRead-only
문서 내에서 특정 문자열을 검색하여 페이지 번호, 문맥, 표 셀 좌표를 반환합니다. file_path는 절대 경로 권장.
Inputs: query (required), file_path (required), context, password.
hwp_table_view문서 표 조회ARead-only
문서 내 표(Table)의 행/열 크기, 병합 정보, 각 셀의 좌표(row, col) 및 텍스트를 반환합니다. table_index(0부터 시작)로 특정 표만 조회할 수 있습니다. file_path는 절대 경로 권장.
Inputs: file_path (required), password, table_index.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
The core read tools (info, get_text, search, table_view) and write tools (replace_text, insert_text, fill_cells, fill_fields) target clearly distinct resources or actions. However, hwp_rhwp_call and hwp_run_plan are broad meta-tools that can perform any edit, creating some genuine overlap with the individual edit tools (e.g., an agent may wonder whether to replace text directly or via a plan/rhwp call).
Every tool uses a consistent hwp_ prefix with snake_case naming throughout (hwp_get_text, hwp_fill_cells, hwp_replace_text, etc.). The verb/noun style is uniform and predictable across the whole set.
14 tools is well-scoped for a document editing server, with each tool covering a distinct lifecycle operation (read, edit, render, history/restore). No tool feels redundant or padding.
Covers a strong surface: metadata, text extraction, search, table inspection, cell/field filling, text replace/insert, render, diff, history, and restore. Minor gaps exist (no dedicated table creation or content deletion), but hwp_rhwp_call and hwp_run_plan provide escape-hatch coverage for those cases.
Maintenance
Related MCP Connectors
Online office suite for AI agents: edit docs, sheets, slides and PDFs in browser or via MCP.
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Create and improve live, shared interactive documents with your agent.
Related MCP Servers
- AlicenseAqualityNot gradedmaintenanceEnables reading, editing, and creating Korean HWPX documents through python-hwpx library. Supports document creation, paragraph/table/image insertion, metadata management, and workspace-restricted file operations with automatic backup functionality.8MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI models to read, create, and edit Korean HWPX documents with advanced support for tables, paragraphs, styles, and images. It features enhanced stability through atomic file writing and smart layout recalculation to prevent document corruption.34MIT
- AlicenseAqualityDmaintenanceEnables AI agents to perform safe, semantic edits on Markdown and DOCX documents through a normalized model with staging, diff review, and stale-edit protection.13MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to edit open HWP/HWPX documents through a single async JavaScript API, performing text, paragraph, table, formatting, and structural changes with save verification, and to render page snapshots or PDFs.MIT