Hangul Word Processor

by jkf87

77 stars

Not rated

GitHub

About

Enables direct creation, editing, and formatting of Korean documents in Hangul Word Processor (HWP) format through Python or Node.js interfaces that control the HWP COM interface.

Details

Author: jkf87
Repository: jkf87/hwp-mcp
GitHub stars: 77
Categories: Productivity, Other, Automation, Developer Tools, Design, Workplace, File Management, AI, Infrastructure, Frontend
Tags: #integration

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Hangul Word Processor

Command (node, npx, python, etc.) python
Arguments
- Argument 1 경로/hwp-mcp/hwp_mcp_stdio_server.py
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

`hwp_create`

Create a new document.

`hwp_insert_text`

Insert specified text into the document. Parameters: text (string).

`hwp_insert_table`

Create a table with specified number of rows and columns. Parameters: rows (integer), cols (integer).

`hwp_fill_table_with_data`

Fill the created table with specified data. Parameters: data (array of arrays), has_header (boolean).

`hwp_fill_column_numbers`

Fill a specified column with consecutive numbers from start to end. Parameters: start (integer), end (integer), column (integer), from_first_cell (boolean).

`hwp_save`

Save the current document to the specified path. Parameters: path (string).

`hwp_batch_operations`

Execute multiple operations in a single batch. Parameters: operations (array of operation objects).

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "hangul word processor": {
            "env": {},
            "args": [
                "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
            ],
            "command": "python"
        }
    }
}

Linux

{
    "env": [],
    "args": [
        "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
    ],
    "command": "python"
}

Macos

{
    "env": [],
    "args": [
        "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
    ],
    "command": "python"
}

Windows

{
    "env": [],
    "args": [
        "\uacbd\ub85c/hwp-mcp/hwp_mcp_stdio_server.py"
    ],
    "command": "python"
}

HWP-MCP (한글 Model Context Protocol)

HWP-MCP는 한글 워드 프로세서(HWP)를 Claude와 같은 AI 모델이 제어할 수 있도록 해주는 Model Context Protocol(MCP) 서버입니다. 이 프로젝트는 한글 문서를 자동으로 생성, 편집, 조작하는 기능을 AI에게 제공합니다.

주요 기능

- 문서 생성 및 관리: 새 문서 생성, 열기, 저장 기능
- 텍스트 편집: 텍스트 삽입, 글꼴 설정, 단락 추가
- 테이블 작업: 테이블 생성, 데이터 채우기, 셀 내용 설정
- 완성된 문서 생성: 템플릿 기반 보고서 및 편지 자동 생성
- 일괄 작업: 여러 작업을 한 번에 실행하는 배치 기능

시스템 요구사항

- Windows 운영체제
- 한글(HWP) 프로그램 설치
- Python 3.7 이상
- 필수 Python 패키지 (requirements.txt 참조)

설치 방법

1. 저장소 클론:

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

cd hwp-mcp

2. 의존성 설치:

pip install -r requirements.txt

3. (선택사항) MCP 패키지 설치:

pip install mcp

사용 방법

Claude와 함께 사용하기

Claude 데스크톱 설정 파일에 다음과 같이 HWP-MCP 서버를 등록하세요:

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

주요 기능 예시

새 문서 생성

hwp_create()

텍스트 삽입

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

테이블 생성 및 데이터 입력

# 테이블 생성
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)

문서 저장

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

일괄 작업 예시

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"}}
])

프로젝트 구조

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  # 보안 모듈

트러블슈팅

보안 모듈 관련 문제

기본적으로 한글 프로그램은 외부에서 파일 접근 시 보안 경고를 표시합니다. 이를 우회하기 위해 FilePathCheckerModuleExample.dll 모듈을 사용합니다. 만약 보안 모듈 등록에 실패해도 기능은 작동하지만, 파일 열기/저장 시 보안 대화 상자가 표시될 수 있습니다.

한글 연결 실패

한글 프로그램이 실행 중이지 않을 경우 연결에 실패할 수 있습니다. 한글 프로그램이 설치되어 있고 정상 작동하는지 확인하세요.

테이블 데이터 입력 문제

테이블에 데이터를 입력할 때 커서 위치가 예상과 다르게 동작하는 경우가 있었으나, 현재 버전에서는 이 문제가 해결되었습니다. 테이블의 모든 셀에 정확하게 데이터가 입력됩니다.

변경 로그

2025-03-27

- 표 생성 및 데이터 채우기 기능 개선 - 표 안에 표가 중첩되는 문제 해결 - 표 생성과 데이터 채우기 기능 분리 - 표 생성 전 현재 커서 위치 확인 로직 추가 - 기존 표에 데이터만 채우는 기능 개선 - 프로젝트 관리 개선 - .gitignore 파일 추가 (임시 파일, 캐시 파일 등 제외)

2025-03-25

- 테이블 데이터 입력 기능 개선 - 첫 번째 셀부터 정확하게 데이터 입력 가능 - 셀 선택 및 커서 위치 설정 로직 개선 - 텍스트 입력 시 커서 위치 유지 기능 추가 - 테이블 전용 도구 모듈(hwp_table_tools.py) 추가 - hwp_fill_column_numbers 함수에 from_first_cell 옵션 추가

라이선스

이 프로젝트는 MIT 라이선스에 따라 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

기여 방법

1. 이슈 제보 또는 기능 제안: GitHub 이슈를 사용하세요.
2. 코드 기여: 변경사항을 포함한 Pull Request를 제출하세요.

연락처

프로젝트 관련 문의는 GitHub 이슈, 코난쌤를 통해 해주세요.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

hwp_create

hwp_insert_text

hwp_insert_table

hwp_fill_table_with_data

hwp_fill_column_numbers

hwp_save

hwp_batch_operations

Claude Desktop / Cursor

Linux

Macos

Windows

HWP-MCP (한글 Model Context Protocol)

주요 기능

시스템 요구사항

설치 방법

사용 방법

Claude와 함께 사용하기

주요 기능 예시

새 문서 생성

텍스트 삽입

테이블 생성 및 데이터 입력

테이블에 데이터 채우기

표에 연속된 숫자 채우기

문서 저장

일괄 작업 예시

프로젝트 구조

트러블슈팅

보안 모듈 관련 문제

한글 연결 실패

테이블 데이터 입력 문제

변경 로그

2025-03-27

2025-03-25

라이선스

기여 방법

관련 프로젝트

연락처

Install

More like this

@mendableai/firecrawl Mcp Server

Umut Naci

Playwright

Sequential Thinking

Time

Filesystem

`hwp_create`

`hwp_insert_text`

`hwp_insert_table`

`hwp_fill_table_with_data`

`hwp_fill_column_numbers`

`hwp_save`

`hwp_batch_operations`