hwp-com-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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)
이 폴더를 통째로 복사한다(예:
C:\hwp_com_mcp)..venv폴더는 복사하지 말 것(PC마다 새로 만듦).setup.bat더블클릭 — 가상환경(.venv)을 만들고 필요한 패키지를 설치한다.점검: 명령 프롬프트에서
.venv\Scripts\python.exe server\doctor.py"ok": true가 나오면 이 PC 에서 한글 자동화가 됩니다. (한글이 잠깐 떴다 사라지는 것이 정상)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 폴더를 앱의 스킬 업로드(설정 → 기능)에 올립니다.
도구
도구 | 하는 일 |
| 이 PC 에서 되는지 점검 |
| 선언형 명세(JSON)로 새 문서 작성 + PDF + 배치 점검 |
| 기존 문서 표 칸 글 수정(서식 유지) |
| 누름틀 양식 템플릿에 값 채우기 |
| 본문·표 칸 글자 찾아 바꾸기 |
| 글·쪽수·필드 이름 읽기 |
| PDF·쪽 그림(PNG)으로 내보내기(눈으로 확인용) |
| 빈 쪽·고아 제목·쪽 밖 글자 점검 |
명세 형식과 예시: 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
자동화하여 HWPX 문서의 로딩, 탐색, 편집, 검증을 한 번에 처리합니다. 문단·표·주석 추가, 텍스트 일괄 치환, 머리말·꼬리말 설정 등 반복 작업을 신속히 수행합니다. 기…
Run saved PDF/office file flows, convert HWP/HWPX to Markdown or DOCX, and call data/text APIs.
Edit AutoCAD and Revit MEP drawings from Claude or ChatGPT in plain English.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to control Hancom's HWP/HWPX documents (Korean word processor) via COM interface on Windows, supporting creation, editing, formatting, and export.MIT
- AlicenseCqualityDmaintenanceEnables LLMs to read and modify HWP (한글) documents via the HWP COM API, with tools for text, tables, formatting, and file conversion.1404MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT
- AlicenseBqualityCmaintenanceEnables 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.22MIT