hwp-mcp-v2

pyhwpx 기반 한글(HWP) 자동화 MCP 서버입니다.

1) 현재 지원 도구

기본 문서 작업

• hwp_connect: 한글 연결

• hwp_status: 연결/활성 문서 상태 조회

• hwp_open: 문서 열기

• hwp_insert_text: 텍스트 입력

• hwp_save_as: 다른 이름으로 저장

• hwp_quit: 한글 종료

문서 탭/창 관리 (1차 확장)

• hwp_list_docs: 열린 문서 목록 조회(0-based index)

• hwp_switch_doc(index): 활성 문서 전환

• hwp_add_tab: 현재 창에 새 탭 문서 추가

• hwp_add_doc: 새 문서 창 추가

• hwp_close_current(save=False): 현재 문서 닫기(기본 저장 안 함)

Related MCP server: HWPX Document Server

2) 요구사항

• Windows

• 한글(HWP) 설치

• Python 3.10+

3) 설치

pip install -r requirements.txt

4) 실행

python hwp_mcp_stdio_server.py

5) Claude/Codex MCP 등록 예시

{
  "mcpServers": {
    "hwp-v2": {
      "command": "python",
      "args": [
        "C:/path/to/hwp-mcp-v2/hwp_mcp_stdio_server.py"
      ]
    }
  }
}

6) 문서 탭 관리 호출 예시

1. hwp_connect

2. hwp_list_docs

3. hwp_add_tab

4. hwp_add_doc

5. hwp_switch_doc(index=1)

6. hwp_close_current(save=false)

7) 응답 포맷

모든 도구는 아래 공통 포맷으로 반환합니다.

{
  "ok": true,
  "message": "작업 결과 메시지",
  "data": {}
}

hwp_list_docs의 data 예시:

{
  "docs": [
    {
      "index": 0,
      "document_id": 123456,
      "full_name": "C:/work/a.hwp",
      "modified": false,
      "is_active": true
    }
  ],
  "count": 1
}

8) 구조

hwp-mcp-v2/
├─ hwp_mcp_stdio_server.py  # MCP 서버 엔트리포인트
├─ requirements.txt
├─ src/
│  ├─ __init__.py
│  └─ service.py            # pyhwpx 래퍼 서비스
└─ tests/
   └─ test_service_doc_tools.py