HWP-MCP (Korean Model Context Protocol)

HWP-MCP is a Model Context Protocol (MCP) server that allows AI models such as Claude to control the Hangul Word Processor (HWP). This project provides AI with the ability to automatically create, edit, and manipulate Hangul documents.

Key Features

• Document Creation and Management: Ability to create, open, and save new documents

• Text editing: insert text, set font, add paragraphs

• Working with tables: creating tables, populating them with data, and setting cell content

• Create finished documents: Automatically generate template-based reports and letters

• Batch operations: Batch function to run multiple operations at once

Related MCP server: hwpConverMdMCP

System Requirements

• Windows operating system

• Installing Hangul (HWP) program

• Python 3.7 or later

• Required Python packages (see requirements.txt)

How to install

1. Clone the repository:

git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp

2. Installing dependencies:

pip install -r requirements.txt

3. (Optional) Install the MCP package:

pip install mcp

How to use

For use with Claude

Register the HWP-MCP server in the Claude desktop settings file as follows:

{
  "mcpServers": {
    "hwp": {
      "command": "python",
      "args": ["경로/hwp-mcp/hwp_mcp_stdio_server.py"]
    }
  }
}

Key Feature Examples

Create a new document

hwp_create()

Insert text

hwp_insert_text("원하는 텍스트를 입력하세요.")

Create a table and enter data

# 테이블 생성
hwp_insert_table(rows=5, cols=2)

# 테이블에 데이터 채우기
hwp_fill_table_with_data([
    ["월", "판매량"], 
    ["1월", "120"], 
    ["2월", "150"], 
    ["3월", "180"], 
    ["4월", "200"]
], has_header=True)

# 표에 연속된 숫자 채우기
hwp_fill_column_numbers(start=1, end=10, column=1, from_first_cell=True)

Save document

hwp_save("경로/문서명.hwp")

Batch operation example

hwp_batch_operations([
    {"operation": "hwp_create"},
    {"operation": "hwp_insert_text", "params": {"text": "제목"}},
    {"operation": "hwp_set_font", "params": {"size": 20, "bold": True}},
    {"operation": "hwp_save", "params": {"path": "경로/문서명.hwp"}}
])

Project Structure

hwp-mcp/
├── hwp_mcp_stdio_server.py  # 메인 서버 스크립트
├── requirements.txt         # 의존성 패키지 목록
├── hwp-mcp-구조설명.md       # 프로젝트 구조 설명 문서
├── src/
│   ├── tools/
│   │   ├── hwp_controller.py  # 한글 제어 핵심 컨트롤러
│   │   └── hwp_table_tools.py # 테이블 관련 기능 전문 모듈
│   ├── utils/                 # 유틸리티 함수
│   └── __tests__/             # 테스트 모듈
└── security_module/
    └── FilePathCheckerModuleExample.dll  # 보안 모듈

Troubleshooting

Security module related issues

By default, Hangul programs display a security warning when accessing files from outside. To bypass this, use the FilePathCheckerModuleExample.dll module. If the security module registration fails, the function will still work, but a security dialog box may be displayed when opening/saving files.

Korean connection failed

If the Hangul program is not running, the connection may fail. Make sure the Hangul program is installed and operating properly.

Table data entry problem

When entering data into a table, the cursor position sometimes behaved differently than expected, but this issue has been resolved in the current version. Data is entered correctly in all cells of the table.

Change Log

2025-03-27

• Improved table creation and data populating capabilities

  • Fix problem with tables nesting within tables

  • Separate table creation and data filling functions

  • Added logic to check current cursor position before creating table

  • Improved ability to fill in data only in existing tables

• Improve project management

  • Add .gitignore file (excluding temporary files, cache files, etc.)

2025-03-25

• Improved table data entry functionality

  • Data can be entered accurately starting from the first cell

  • Improved cell selection and cursor positioning logic

  • Added ability to maintain cursor position when entering text

• Add table-only tool module ( hwp_table_tools.py )

• Add from_first_cell option to hwp_fill_column_numbers function

License

This project is distributed under the MIT License. See the LICENSE file for details.

How to contribute

1. To report an issue or suggest a feature: Use GitHub issues.

2. Contribute code: Submit a Pull Request with your changes.

Related Projects

• HWP SDK : Official SDK of Hangul and Computer

• Cursor MCP

• Smithery

contact

For project-related inquiries, please contact Conan through GitHub Issues.