HWP MCP服务器
MCP（模型上下文协议）服务器，使LLM能够通过HWP COM API读取和修改二进制HWP（韩语）文档。
建筑
LLM ↔ MCP Server (Python/FastMCP) ↔ PowerShell Bridge (JSON stdin/stdout) ↔ HWP COM API ↔ 한글
Python MCP服务器管理一个长时间运行的PowerShell子进程，该子进程承载HWP COM对象。
需求
- 视窗 （HWP COM API仅支持Windows）
- 韩公司韩文 已安装（提供HWP COM服务器）
- PowerShell 5.1+ （随Windows附带）
- Python>=3.11
安装
用法
运行MCP服务器
python -m hwp_mcp.server
Claude桌面配置
{
"mcpServers": {
"hwp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/hwp-mcp", "hwp-mcp"]
}
}
}
MCP工具（140）
HWP COM API 199 HParameterSet 100%覆盖
文件管理（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 |
单位换算（mm、pt、hwpunit） |
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枚举值 |
H参数集操作（10）
| 工具 |
说明 |
H参数集计数 |
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 instance & shared helpers
│ ├── server.py # Entry point, imports all tool modules
│ ├── bridge.py # PowerShell subprocess manager
│ ├── commands.py # JSON command builders
│ └── tools/ # MCP tool definitions (140 tools)
│ ├── 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 bridge dispatcher
│ └── handlers/ # 12 handler modules
│ ├── 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 # Bridge unit tests
│ ├── test_commands.py # Command builder unit tests
│ └── test_server.py # Server tool unit tests
└── pyproject.toml
发展
uv pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
局限性
- 仅限Windows：HWP COM API需要Windows
- 韩文required：必须安装Hancom Office韩文
- 仅限二进制HWP：HWPX（基于XML）需要单独的服务器
许可证
麻省理工学院
