HWP-MCP（韩国模型上下文协议）

HWP-MCP 是一个模型上下文协议 (MCP) 服务器，允许 Claude 等 AI 模型控制韩文文字处理器 (HWP)。该项目为AI提供了自动创建、编辑和操作韩语文档的能力。

主要特点

文档创建和管理：能够创建、打开和保存新文档
文本编辑：插入文本、设置字体、添加段落
使用表格：创建表格、填充数据以及设置单元格内容
创建完成的文档：自动生成基于模板的报告和信函
批量操作：批量功能可同时运行多个操作

系统要求

Windows操作系统
安装韩语（HWP）程序
Python 3.7 或更高版本
所需的 Python 包（请参阅 requirements.txt）

如何安装

克隆存储库：

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

安装依赖项：

pip install -r requirements.txt

（可选）安装 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年3月27日

改进的表格创建和数据填充功能
- 修复表格嵌套在表格中的问题
- 单独的表格创建和数据填充功能
- 添加了在创建表之前检查当前光标位置的逻辑
- 改进了仅在现有表中填写数据的能力
改进项目管理
- 添加.gitignore文件（排除临时文件、缓存文件等）

2025年3月25日

改进的表格数据输入功能
- 从第一个单元格开始即可准确输入数据
- 改进的单元格选择和光标定位逻辑
- 增加了输入文本时保持光标位置的功能
添加仅表格工具模块（ hwp_table_tools.py ）
将from_first_cell选项添加到hwp_fill_column_numbers函数

执照

该项目根据 MIT 许可证分发。请参阅LICENSE文件以了解详细信息。

如何贡献

要报告问题或建议功能：使用 GitHub 问题。
贡献代码：提交包含您更改的 Pull 请求。

接触

如有项目相关疑问，请通过 GitHub Issues 联系Conan 。

HWP MCP Server