HWP-MCP (한글 Model Context Protocol)

HWP-MCP 是一个 Model Context Protocol (MCP) 服务器，它使 Claude 等 AI 模型能够控制韩文文字处理软件（HWP）。该项目为 AI 提供了自动创建、编辑和操作韩文文档的功能。

主要功能

• 文档生成与管理：创建新文档、打开、保存功能
• 文本编辑：插入文本、设置字体、添加段落
• 表格操作：创建表格、填充数据、设置单元格内容
• 生成完成的文档：基于模板自动生成报告和信件
• 批量作业：一次执行多个任务的批处理功能

系统要求

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

安装方法

1. 克隆仓库：

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

1. 安装依赖项：

pip install -r requirements.txt

1. （可选）安装 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 Issues。
2. 代码贡献：提交包含更改的 Pull Request。

相关项目

• HWP SDK: 韩国计算机公司的官方 SDK
• Cursor MCP
• Smithery

联系方式

有关项目的任何查询，请通过 GitHub Issues 或 코난쌤 进行联系。