hwp-mcp

🚀 HWP MCP 服务器

HWP MCP 服务器借助 HWP COM API，使大语言模型（LLMs）能够读取和修改二进制 HWP（韩文字处理软件文档）文件。

🚀 快速开始

运行 MCP 服务器

python -m hwp_mcp.server

Claude 桌面配置

{
  "mcpServers": {
    "hwp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hwp-mcp", "hwp-mcp"]
    }
  }
}

✨ 主要特性

• 支持大语言模型通过 HWP COM API 读取和修改二进制 HWP 文档。
• 提供丰富的工具集，涵盖文档管理、读写、格式设置、表格操作等多个方面。

📦 安装指南

uv pip install -e .

💻 使用示例

基础用法

# 运行 MCP 服务器
python -m hwp_mcp.server

📚 详细文档

MCP 工具（140 个）

文档管理（5 个）

| 工具 | 描述 | |------|-------------| | open_document | 打开 HWP 文档 | | close_document | 关闭文档 | | list_open_documents | 列出已打开的文档 | | save_document | 保存文档 | | save_document_as | 以不同名称/格式保存文档 |

读取（5 个）

| 工具 | 描述 | |------|-------------| | get_document_text | 提取全文 | | get_paragraphs | 获取段落列表 | | get_tables | 获取表格列表 | | get_table_data | 获取表格数据（二维数组） | | search_text | 搜索文本 |

写入（5 个）

| 工具 | 描述 | |------|-------------| | replace_text | 替换文本 | | insert_text | 插入文本 | | set_table_cell_text | 设置表格单元格文本 | | append_paragraph | 追加段落 | | set_text_file | 根据文本数据设置文档内容 |

格式设置（3 个）

| 工具 | 描述 | |------|-------------| | set_text_style | 字符格式设置（字体、大小、加粗、颜色等） | | set_paragraph_style | 段落格式设置（对齐方式、行间距） | | set_page_style | 页面格式设置（页边距、方向） |

表格（3 个）

| 工具 | 描述 | |------|-------------| | create_table | 创建表格 | | add_table_row | 添加表格行 | | delete_table_row | 删除表格行 |

高级操作（5 个）

| 工具 | 描述 | |------|-------------| | run_hwp_action | 执行任意 HWP 操作（高级用户） | | convert_to_hwpx | 将 HWP 转换为 HWPX | | convert_to_pdf | 将 HWP 转换为 PDF | | batch_convert_files | 批量转换文件（HWP、PDF、DOCX 等） | | set_file_security | 文件安全设置（复制/打印限制） |

光标与导航（11 个）

| 工具 | 描述 | |------|-------------| | move_cursor | 将光标移动到指定位置 | | get_cursor_position | 获取当前光标位置 | | set_cursor_position | 设置光标位置（列表、段落、位置） | | get_pos_by_set | 获取光标位置作为集合 | | set_pos_by_set | 根据集合设置光标位置 | | get_selected_pos_by_set | 获取选择的起始/结束位置 | | select_text | 通过坐标选择文本范围 | | get_selection_info | 获取当前选择信息 | | clear_selection | 清除选择 | | delete_selection | 删除所选内容 | | init_scan | 初始化文档扫描 |

字段（12 个）

| 工具 | 描述 | |------|-------------| | create_field | 创建命名字段（模板占位符） | | field_exists | 检查字段是否存在 | | get_field_list | 获取所有字段名称 | | get_field_text | 读取字段文本 | | put_field_text | 设置字段文本 | | get_current_field | 获取光标处的字段名称 | | set_current_field_name | 设置当前字段名称 | | move_to_field | 将光标移动到字段 | | rename_field | 重命名字段 | | modify_field_properties | 修改字段属性 | | set_field_ctrl_properties | 设置字段控件属性 | | batch_fill_fields | 批量填充多个字段 |

高级表格（11 个）

| 工具 | 描述 | |------|-------------| | add_table_column | 添加表格列 | | delete_table_column | 删除表格列 | | merge_table_cells | 合并单元格 | | split_table_cell | 拆分单元格 | | set_table_cell_style_adv | 单元格样式（背景、垂直对齐） | | set_table_border_adv | 表格边框样式 | | table_to_text | 表格转换为文本 | | text_to_table | 文本转换为表格 | | swap_table_row_col | 交换表格行/列 | | apply_table_template | 应用表格模板 |

增强格式设置（5 个）

| 工具 | 描述 | |------|-------------| | set_char_shape | 扩展字符属性（字距、间距、阴影等） | | set_bullet_style | 项目符号样式 | | set_numbering_style | 编号样式 | | set_tab_definition | 制表位 | | manage_style | 创建/删除/应用样式 |

页面与章节（10 个）

| 工具 | 描述 | |------|-------------| | set_section_definition | 章节定义（装订边距、文本流向） | | set_page_border | 页面边框和背景 | | set_columns | 多列布局 | | set_page_number | 页码 | | set_header_footer | 页眉/页脚 | | set_footnote_style | 脚注样式 | | set_master_page | 母版页 | | set_page_hiding | 隐藏页面元素（页眉/页脚等） | | set_page_num_ctrl | 页码控制（重新开始编号） | | set_text_direction | 文本方向（水平/垂直） |

图像与公式（3 个）

| 工具 | 描述 | |------|-------------| | insert_picture | 插入图片 | | insert_background_picture | 插入背景图片 | | create_equation | 插入公式 |

表单控件（3 个）

| 工具 | 描述 | |------|-------------| | insert_form_control | 插入表单控件（按钮、复选框等） | | set_form_properties | 设置表单控件属性 | | get_form_data | 读取表单数据 |

文档信息（5 个）

| 工具 | 描述 | |------|-------------| | get_document_info | 文档元数据（页数、修改状态） | | get_document_summary | 文档摘要（标题、作者） | | get_page_text | 提取特定页面的文本 | | get_page_count | 总页数 | | export_page_as_image | 将页面导出为图像 |

打印与导出（3 个）

| 工具 | 描述 | |------|-------------| | print_document | 打印文档 | | set_watermark | 设置水印（文本/图像） | | save_as_image | 将文档保存为图像 |

实用工具（4 个）

| 工具 | 描述 | |------|-------------| | convert_units | 单位转换（毫米、磅、HWP 单位） | | rgb_color | RGB/十六进制颜色转换为 HWP 颜色值 | | run_macro | 运行 HWP 宏 | | get_file_info | 获取文件元数据（无需打开） |

书签与超链接（6 个）

| 工具 | 描述 | |------|-------------| | insert_bookmark | 插入书签 | | insert_hyperlink | 插入超链接 | | hyperlink_jump | 跳转到超链接目标 | | insert_index_mark | 插入索引标记 | | insert_auto_number | 插入自动编号字段 | | insert_cross_reference | 插入交叉引用 |

页眉/页脚与标题（2 个）

| 工具 | 描述 | |------|-------------| | set_drop_cap | 首字下沉（装饰性首字母） | | set_caption | 表格/图像标题 |

文档操作（8 个）

| 工具 | 描述 | |------|-------------| | sort_text | 对文本进行排序 | | spell_check | 拼写检查 | | set_track_changes | 跟踪更改 | | mail_merge | 邮件合并 | | make_table_of_contents | 生成目录 | | insert_file | 插入另一个文件 | | set_password | 设置文档密码 | | save_block | 将选择内容保存到文件 |

兼容性与设置（3 个）

| 工具 | 描述 | |------|-------------| | set_compatible_document | 文档兼容模式 | | set_view_properties | HWP 视图属性（缩放、视图模式等） | | set_engine_properties | HWP 引擎属性（拼写检查、自动保存等） |

控件与对象（4 个）

| 工具 | 描述 | |------|-------------| | delete_ctrl | 删除所选控件 | | find_ctrl | 查找控件 | | check_x_object | 检查 X 对象是否存在 | | release_scan | 释放扫描资源 |

样式与脚本（4 个）

| 工具 | 描述 | |------|-------------| | import_style | 导入样式 | | export_style | 导出样式 | | run_script | 运行 HWP 脚本 | | get_script_source | 获取脚本源代码 |

系统与安全（11 个）

| 工具 | 描述 | |------|-------------| | register_module | 注册 COM 模块 | | set_drm_authority | DRM 权限 | | lock_command | 锁定/解锁命令 | | is_command_lock | 检查命令锁定状态 | | set_message_box_mode | 消息框模式 | | get_message_box_mode | 获取消息框模式 | | is_action_enable | 检查操作是否启用 | | replace_action | 替换操作处理程序 | | get_hwp_property | 获取 HWP COM 属性 | | set_hwp_property | 设置 HWP COM 属性 | | hwp_enum | 字符串转换为 HWP 枚举值 |

HParameterSet 操作（10 个）

| 工具 | 描述 | HParameterSet 数量 | |------|-------------|---------------------| | hwp_table_param_action | 表格操作 | 14 | | hwp_file_param_action | 文件操作 | 11 | | hwp_draw_param_action | 绘图对象操作 | 22 | | hwp_shape_param_action | 形状操作 | 6 | | hwp_style_param_action | 样式/边框操作 | 6 | | hwp_form_param_action | 表单操作 | 13 | | hwp_doc_info_param_action | 文档信息操作 | 9 | | hwp_hanja_param_action | 汉字/转换操作 | 11 | | hwp_selection_param_action | 选择/位置操作 | 6 | | hwp_misc_param_action | 杂项操作 | 69 |

项目结构

hwp-mcp/
├── src/hwp_mcp/
│   ├── __init__.py
│   ├── _core.py         # FastMCP 实例与共享辅助函数
│   ├── server.py        # 入口点，导入所有工具模块
│   ├── bridge.py        # PowerShell 子进程管理器
│   ├── commands.py      # JSON 命令构建器
│   └── tools/           # MCP 工具定义（140 个工具）
│       ├── cursor.py
│       ├── doc_info.py
│       ├── document.py
│       ├── drawing.py
│       ├── field.py
│       ├── form.py
│       ├── formatting.py
│       ├── hparam.py
│       ├── hwpobject.py
│       ├── page_section.py
│       ├── print_export.py
│       ├── system.py
│       ├── table.py
│       ├── text.py
│       └── utility.py
├── scripts/
│   ├── hwp_bridge.ps1   # PowerShell COM 桥接调度器
│   └── handlers/        # 12 个处理模块
│       ├── document.ps1
│       ├── text.ps1
│       ├── table.ps1
│       ├── style_format.ps1
│       ├── action.ps1
│       ├── cursor_selection.ps1
│       ├── field.ps1
│       ├── draw_object.ps1
│       ├── form_control.ps1
│       ├── document_info.ps1
│       ├── print_export.ps1
│       ├── utility.ps1
│       └── hwpobject_methods.ps1
├── tests/
│   ├── test_bridge.py   # 桥接单元测试
│   ├── test_commands.py # 命令构建器单元测试
│   └── test_server.py   # 服务器工具单元测试
└── pyproject.toml

开发

uv pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/

🔧 技术细节

Python MCP 服务器管理一个长期运行的 PowerShell 子进程，该子进程托管 HWP COM 对象。架构如下：

LLM ↔ MCP Server (Python/FastMCP) ↔ PowerShell Bridge (JSON stdin/stdout) ↔ HWP COM API ↔ 한글

📄 许可证

本项目采用 MIT 许可证。

⚠️ 局限性

• 仅支持 Windows：HWP COM API 仅在 Windows 系统上可用。
• 需要安装韩文字处理软件：必须安装 한컴오피스 한글。
• 仅支持二进制 HWP 文件：基于 XML 的 HWPX 文件需要单独的服务器。