Skip to main content
Glama

hwp-com-mcp — 한글(HWP) 문서 작성·수정 MCP 서버 + Claude 스킬

한글 프로그램을 화면 없이 직접 조종(COM)해서 문서를 만들고 고칩니다. 파일을 따로 해석해서 다시 쓰는 방식이 아니라 한글이 직접 저장하므로 표가 찌그러지거나 쪽 배치가 어긋나지 않습니다. (한글 2010 에서 179개 항목 시험, 176개 통과 — selftest/ 참고)

필요한 것

  • Windows PC, 한컴오피스 한글이 설치돼 있을 것 (한글 2010 에서 검증, 다른 버전은 selftest 로 확인)

  • Python 3.9 이상 (https://www.python.org/downloads/ — 설치 때 "Add python.exe to PATH" 체크)

  • Claude Code 또는 Claude 데스크톱 앱

Related MCP server: HWP MCP Server

설치 (새 PC)

  1. 이 폴더를 통째로 복사한다(예: C:\hwp_com_mcp). .venv 폴더는 복사하지 말 것(PC마다 새로 만듦).

  2. setup.bat 더블클릭 — 가상환경(.venv)을 만들고 필요한 패키지를 설치한다.

  3. 점검: 명령 프롬프트에서

    .venv\Scripts\python.exe server\doctor.py

    "ok": true 가 나오면 이 PC 에서 한글 자동화가 됩니다. (한글이 잠깐 떴다 사라지는 것이 정상)

  4. Claude 에 연결 — 아래 중 하나.

A. Claude Code — 가장 쉬움

install_user.bat 실행(MCP 서버 등록 + 스킬 설치). 이후 Claude Code 를 다시 시작.

B. Claude Code — 플러그인으로

claude --plugin-dir C:\hwp_com_mcp

(.claude-plugin/plugin.json, .mcp.json, skills/ 를 그대로 읽습니다. 회사 저장소에 올려 마켓플레이스로 배포할 수도 있습니다.)

C. Claude 데스크톱 앱

%APPDATA%\Claude\claude_desktop_config.json 의 mcpServers 에 추가:

{"mcpServers": {"hwp-com": {"command": "C:\\hwp_com_mcp\\.venv\\Scripts\\python.exe", "args": ["C:\\hwp_com_mcp\\server\\server.py"]}}}

스킬은 skills\hwp-report 폴더를 앱의 스킬 업로드(설정 → 기능)에 올립니다.

도구

도구

하는 일

hwp_doctor

이 PC 에서 되는지 점검

hwp_build

선언형 명세(JSON)로 새 문서 작성 + PDF + 배치 점검

hwp_edit_cells

기존 문서 표 칸 글 수정(서식 유지)

hwp_fill_fields

누름틀 양식 템플릿에 값 채우기

hwp_replace_text

본문·표 칸 글자 찾아 바꾸기

hwp_read

글·쪽수·필드 이름 읽기

hwp_export

PDF·쪽 그림(PNG)으로 내보내기(눈으로 확인용)

hwp_check_pdf

빈 쪽·고아 제목·쪽 밖 글자 점검

명세 형식과 예시: skills/hwp-report/references/spec.md

안전 장치

  • 한글은 임시 폴더(%TEMP%) 밖 파일을 열면 "접근 허용" 창을 띄워 멈춥니다. 모든 도구는 원본을 임시 폴더로 복사해 작업하고 결과만 일반 복사로 돌려놓으므로 이 창이 뜨지 않습니다. (창이 뜨면 이 도구가 아닌 다른 경로로 한글을 연 것입니다. 승인 DLL 은 등록하지 않습니다.)

  • 원본을 덮어쓰기 전에 %USERPROFILE%\hwp_com_backup(환경변수 HWP_COM_BACKUP 로 변경)에 백업합니다.

  • 한글이 멈추면 시간 제한 뒤 이 도구가 띄운 한글 프로세스만 종료합니다(사용자가 쓰던 한글은 건드리지 않음).

알려진 한계

꼬리말 글자·글상자·자동 차례 불가, HWPX(한글 2010) 불가, 장평 글자 PDF 변환 누락 — 자세히는 skills/hwp-report/SKILL.md.

다른 버전 한글에서 확인하려면

.venv\Scripts\python.exe selftest\run_all.py

(약 12분, 한글이 화면 없이 반복해서 뜹니다. 결과는 selftest\out\res_*.json.) 통과/실패 목록을 보고 쓸 수 있는 기능을 판단하세요.

구성

server/server.py        MCP 서버(도구 정의)
server/hwp_com/         한글 조종 코드 (hwp_toolkit·hwp_fmt·render·hwp_qa, pyhwpx 복사본 — pyhwpx_license.txt 참고. 안 쓰는 승인 DLL 은 뺐음)
skills/hwp-report/      Claude 용 사용 지침 + 명세 문서
selftest/               기능 시험 일체

라이선스

MIT (LICENSE). server/hwp_com/pyhwpx 는 pyhwpx(MIT) 복사본이며 자체 라이선스를 따릅니다.

개발 메모 (시행착오)

  • MCP 서버 안에서 한글 호출 스레드가 pyhwpx 를 처음 import 하면 멈춤 → server.py 가 시작할 때 미리 import.

  • mcp 패키지는 2.x 에서 FastMCP 이름이 바뀌어 requirements.txt 에서 <2 로 고정.

  • 디버그: 환경변수 HWP_COM_DEBUG=1 이면 서버가 stderr 로 진행 단계를 찍는다.

안내

비공식 도구입니다. "한글", "한컴오피스"는 주식회사 한글과컴퓨터의 상표이며 이 프로젝트와 제휴·후원 관계가 없습니다. 한글 프로그램은 별도로 설치(라이선스 보유)해야 하고, 이 도구는 설치된 한글을 자동화(COM)할 뿐 한글 프로그램을 포함하지 않습니다.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control Hancom's HWP/HWPX documents (Korean word processor) via COM interface on Windows, supporting creation, editing, formatting, and export.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to read and edit Korean HWP/HWPX documents, including converting Hanyang PUA old-Hangul characters to Unicode jamo, diagnosing unsupported characters, and preserving arae-a, panch'im, yet-ieung, expanded jamo, filler and side dots. Also supports HWPX search-and-replace, template filling, paragraph/table/image/style editing, page rendering to SVG/HTML, and creating new HWPX documents.
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables creating, editing, and reading Korean Hangul word-processor documents (.hwpx and .hwp) locally through Claude Desktop or VS Code, with no network or separate machine required. Provides tools for text, formatting, tables, images, charts, equations, footnotes, hyperlinks, and fields, and can export to PDF or convert .hwp files to .hwpx when Hangul is installed on Windows.
      22
      MIT