hwpctl

열린 한/글 2022 문서를 AI 코딩 도구가 직접 편집하게 하는 로컬 MCP·CLI 브리지 A local MCP/CLI bridge that lets AI coding agents edit an open Hancom Office Hangul 2022 document.

한국어 · English

flowchart LR
    U["사용자 · User"] --> A["Claude Code · Codex · Cursor<br/>Gemini CLI · Grok Build"]
    A -->|"로컬 MCP stdio"| B["hwpctl<br/>단일 작성기 · 명령 잠금"]
    B -->|"Windows COM (win32com)"| H["열어 둔 한글 2022 문서<br/>Open Hangul 2022 document"]
    H -->|"화면에서 즉시 확인"| U

한국어

hwpctl은

Claude Code, Codex, Cursor, Gemini CLI, Grok Build 같은 AI 도구가 사용자가 열어 둔 한글 2022 창을 Windows COM으로 직접 고치게 합니다. 바뀐 내용은 한/글 화면에서 바로 확인합니다. 클라이언트마다 한/글 로직을 따로 두지 않고, 설정만 바꿔 같은 hwpctl 서버에 붙습니다.

새 문서에서 미리보기 후 적용하는 좁고 안전한 방식이 필요하면 HWP Live Safe를, 클라이언트·엔진 조합 안내는 HWP AI Bridge를 보세요.

빠른 시작

요구 사항: Windows, 한글 2022(검증 빌드 12.0.0.850), Python 3.10 이상.

1. 전용 가상환경에 설치합니다. MCP 서버 실행 파일이 소스 폴더에 묶이지 않도록 -e 설치는 피합니다.

py -3.13 -m venv C:\hwpctl\venv
C:\hwpctl\venv\Scripts\python -m pip install "hwpctl[windows] @ https://github.com/Jasujung99/hwpctl/releases/download/v0.2.1/hwpctl-0.2.1-py3-none-any.whl"

2. AI 클라이언트에 등록합니다. Claude Code 예:

claude mcp add hwpctl -- C:\hwpctl\venv\Scripts\hwpctl.exe mcp

Codex·Cursor·Gemini CLI·Grok Build 설정은 클라이언트 연결에 있습니다.

3. 한글 2022에서 문서를 하나 열고 확인합니다.

C:\hwpctl\venv\Scripts\hwpctl doctor
C:\hwpctl\venv\Scripts\hwpctl status

이제 AI에게 "이 문서에 4열 8행 표를 넣고 첫 행을 회색으로 해 줘"처럼 요청하면 됩니다. 업데이트할 때는 MCP 클라이언트를 모두 종료한 뒤 다시 설치합니다(설치).

대표 도구

전체 55개 도구: 도구 레퍼런스

안전 원칙

• 자동 저장하지 않습니다. save_as는 새 경로만 받고, 원본 덮어쓰기는 save --overwrite가 필요합니다.

• 문서 닫기는 --force, 수정본을 버리고 다른 파일 열기는 --discard를 명시해야 합니다.

• 명령 단위 잠금으로 한 번에 하나의 작성기만 문서를 고칩니다.

• 한/글 대화상자가 떠 있으면 대신 누르지 않고 한국어 오류로 멈춥니다.

• hwpctl 명령 사이에 직접 편집했다면 undo 대신 한/글의 Ctrl+Z를 쓰세요.

자세히: 안전 장치 · 알려진 한계

문서

• 사용 가이드: 설치 · 클라이언트 연결 · 도구 레퍼런스 · 표와 서식 · 차트 · 글맵시 · HWPX 작성(실험) · 안전 장치

• 알려진 한계 · 변경 기록 · 보안 정책 · 기여 안내 · 제3자 고지 · 전체 문서 목록

범위와 라이선스

hwpctl은 독립적인 오픈 소스 프로젝트이며 한글과컴퓨터가 제공·보증·후원하는 공식 제품이 아닙니다. 사용자는 유효한 한글 라이선스와 해당 자동화 사용 조건을 직접 확인해야 합니다. 이 저장소의 코드는 MIT 라이선스로 배포되며, 한글 및 제3자 패키지는 각자의 라이선스를 따릅니다.

Related MCP server: HWP-MCP

English

What is hwpctl?

hwpctl lets AI coding agents such as Claude Code, Codex, Cursor, Gemini CLI and Grok Build edit the Hancom Office Hangul 2022 document you already have open, through Windows COM. Every change appears live in the Hangul window. Clients carry no Hangul-specific logic; they all connect to the same hwpctl server with a small configuration change.

For a narrower, preview-first workflow on a new document, see HWP Live Safe. For choosing a client and engine combination, see HWP AI Bridge.

Quick start

Requirements: Windows, Hancom Office Hangul 2022 (verified build 12.0.0.850), Python 3.10+.

1. Install into a dedicated virtual environment. Avoid editable (-e) installs for the MCP runtime, so the server executable is not tied to a source checkout.

py -3.13 -m venv C:\hwpctl\venv
C:\hwpctl\venv\Scripts\python -m pip install "hwpctl[windows] @ https://github.com/Jasujung99/hwpctl/releases/download/v0.2.1/hwpctl-0.2.1-py3-none-any.whl"

2. Register it with your client. Claude Code example:

claude mcp add hwpctl -- C:\hwpctl\venv\Scripts\hwpctl.exe mcp

Configurations for Codex, Cursor, Gemini CLI and Grok Build are in client setup.

3. Open a document in Hangul 2022 and check the connection.

C:\hwpctl\venv\Scripts\hwpctl doctor
C:\hwpctl\venv\Scripts\hwpctl status

Then ask your agent, for example: "Insert a 4-column, 8-row table with a gray header row." To update, quit every MCP client first, then reinstall (install guide).

Key tools

All 55 tools: tool reference

Safety

• No autosave. save_as only writes to a new path; overwriting the original requires save --overwrite.

• Closing a document requires --force; discarding changes to open another file requires --discard.

• A per-command lock keeps a single writer on the document at a time.

• If a Hangul dialog is open, hwpctl stops with an error instead of clicking it for you.

• If you edited the document by hand between hwpctl commands, use Ctrl+Z in Hangul instead of undo.

Details: safety · known limitations

Documentation

The detailed guides are currently written in Korean.

• Guides: install · client setup · tool reference · tables and formatting · charts · TextArt · HWPX authoring (experimental) · safety

• Known limitations · Changelog · Security · Contributing · Third-party notices · All docs

Scope and license

hwpctl is an independent open-source project. It is not provided, endorsed or sponsored by Hancom Inc. You are responsible for holding a valid Hangul license and following its automation terms. The code in this repository is released under the MIT License; Hangul and third-party packages follow their own licenses.