HWP MCP Server

한글(HWP) 문서 자동화를 위한 Model Context Protocol (MCP) 서버

개요

이 프로젝트는 한글과컴퓨터의 HWP 문서를 Claude Desktop을 통해 자동화할 수 있게 해주는 MCP 서버입니다.

주요 특징

✅ 타입 안전성: Idris2 형식 명세 기반 상태 관리
✅ 상태 전환 검증: 문서 생명주기 자동 관리 (Closed → Opened → Modified → Saved)
✅ COM 자동화: pywin32를 통한 한글 COM API 연동
✅ MCP 표준: Claude Desktop과 완전 호환

필요 조건

OS: Windows (한글 프로그램 필요)
Python: 3.10 이상
한글: 한글과컴퓨터 워드프로세서 설치 필요
패키지 관리자: uv 권장

설치

1. uv로 설치 (권장)

# uv 설치 (없는 경우)
pip install uv

# 프로젝트 의존성 설치
uv pip install -e .

2. pip로 설치

pip install -e .

Claude Desktop 설정

claude_desktop_config.json 파일에 다음 내용 추가:

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hwp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\YourName\\Projects\\HwpAutomation",
        "run",
        "python",
        "-m",
        "src.server"
      ]
    }
  }
}

사용 가능한 도구 (Tools)

1. `hwp_create_document`

새 한글 문서 생성

상태 전환: Closed → Opened
파라미터: 없음

2. `hwp_open_document`

기존 한글 문서 열기

상태 전환: Closed → Opened
파라미터:
  - path (string): 열 파일 경로

3. `hwp_close_document`

현재 문서 닫기

상태 전환: Opened → Closed
파라미터: 없음

4. `hwp_save_document`

문서 저장

상태 전환: Modified → Saved
파라미터: 없음

5. `hwp_insert_text`

텍스트 삽입

상태 전환: Opened → Modified
파라미터:
  - text (string): 삽입할 텍스트

6. `hwp_create_table`

표 만들기

상태 전환: Opened → Modified
파라미터:
  - rows (integer): 행 개수
  - cols (integer): 열 개수

7. `hwp_get_document_state`

현재 문서 상태 조회

파라미터: 없음
반환: 문서 상태 및 경로 정보

사용 예제

Claude Desktop에서 다음과 같이 요청할 수 있습니다:

새 한글 문서를 만들고 "안녕하세요, MCP!"라는 텍스트를 넣어주세요.
그리고 3x3 표를 하나 만들어주세요.

Claude가 자동으로:

hwp_create_document 호출
hwp_insert_text 호출
hwp_create_table 호출

아키텍처

디렉토리 구조

HwpAutomation/
├── Specs/
│   └── HwpMCP.idr          # Idris2 형식 명세
├── HwpBooks/
│   └── ActionTable_2504.pdf # 한글 Action 참조 문서
├── src/
│   ├── __init__.py
│   ├── types.py            # 타입 정의 (Idris 스펙 기반)
│   ├── hwp_client.py       # HWP COM 클라이언트
│   ├── tools.py            # MCP 도구 정의
│   └── server.py           # MCP 서버 진입점
├── pyproject.toml
├── README.md
└── claude.md               # 개발 로그

상태 다이어그램

Closed ──create/open──> Opened ──insert_text/create_table──> Modified
  ↑                        ↓                                      ↓
  └────── close ───────────┘                                      │
                                                                  │
                                         Saved <───── save ───────┘

개발

Idris2 스펙 컴파일

cd Specs
idris2 HwpMCP.idr -o build/hwp_mcp

타입 검증

mypy src/

테스트

pytest tests/

참고 자료

MCP Specification
Claude Desktop MCP
HWP COM API: HwpBooks/ActionTable_2504.pdf
Idris2 Spec: Specs/HwpMCP.idr

라이선스

MIT License

기여

이슈 및 Pull Request 환영합니다!

문제 해결

HWP 프로그램이 열리지 않는 경우

한글과컴퓨터 워드프로세서가 설치되어 있는지 확인
Windows에서만 동작합니다

COM 초기화 오류

uv pip install --upgrade pywin32
python -m win32com.client.makepy "HWPFrame.HwpObject"

권한 오류

관리자 권한으로 실행
한글 프로그램이 다른 프로세스에서 사용 중이지 않은지 확인

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.claude		.claude
CodeReview		CodeReview
ErrorImages		ErrorImages
FunctionTest		FunctionTest
HwpBooks		HwpBooks
HwpIdris		HwpIdris
Schema		Schema
Scripts		Scripts
Security		Security
Specs		Specs
Tests		Tests
automations		automations
core		core
ui		ui
.gitignore		.gitignore
HwpAutomation.spec		HwpAutomation.spec
IDRIS2_USAGE.md		IDRIS2_USAGE.md
README.md		README.md
README_V2.md		README_V2.md
TODO.md		TODO.md
build.bat		build.bat
check_specs.sh		check_specs.sh
claude.md		claude.md
claude_desktop_config.json		claude_desktop_config.json
pyproject.toml		pyproject.toml
run_ui.py		run_ui.py
test_naming.py		test_naming.py

Folders and files

Latest commit

History

Repository files navigation

HWP MCP Server

개요

주요 특징

필요 조건

설치

1. uv로 설치 (권장)

2. pip로 설치

Claude Desktop 설정

사용 가능한 도구 (Tools)

1. hwp_create_document

2. hwp_open_document

3. hwp_close_document

4. hwp_save_document

5. hwp_insert_text

6. hwp_create_table

7. hwp_get_document_state

사용 예제

아키텍처

디렉토리 구조

상태 다이어그램

개발

Idris2 스펙 컴파일

타입 검증

테스트

참고 자료

라이선스

기여

문제 해결

HWP 프로그램이 열리지 않는 경우

COM 초기화 오류

권한 오류

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `hwp_create_document`

2. `hwp_open_document`

3. `hwp_close_document`

4. `hwp_save_document`

5. `hwp_insert_text`

6. `hwp_create_table`

7. `hwp_get_document_state`

Packages