Advanced HWP MCP Server

高级HWP MCP服务器

高级韩文（HWP）MCP服务器-可以控制韩文的所有功能的MCP服务器。

🚀 主要功能

控制默认文档

• 创建新文档（create_document)
• 打开文档（open_document) - NEW!自动处理所有对话框+显示窗口顶部

- 自动处理版本警告 - 自动批准访问权限检查 - 自动跳过密码输入 - 韩文窗口自动显示在屏幕最前面

• 保存文档（save_document)
• 关闭文档（close_document)
• 关闭所有文档（close_all_documents)
• 韩文结束（quit_hwp)
• 查询文档信息（get_document_info)

正在运行的韩文连接

• 查询打开的文档列表（get_running_hwp_documents)
• 连接到正在运行的韩文（connect_to_running_hwp)
• 切换到特定文档（switch_to_document)
• 浏览活动文档信息（get_active_document_info)
• 浏览所有韩文窗口列表（list_all_hwp_windows)
• 连接到特定的韩文窗口（connect_to_hwp_window）-注意：使用COM限制检查窗口

⚠️ 重要：双击多个韩文文件，每个文件都以单独的过程运行。 COM只能连接到一个进程，因此无法直接控制其他进程中的文档。 请参见下面的“推荐工作流”部分。

高级文本操作

• 设置精确的文本位置（insert_text_at_position)
• 选择文本范围（select_text_range)
• 查找/替换（find_and_replace)
• 插入纯文本（insert_text)

完全的格式控制

• 设置字体格式（apply_font_format)
• 设置段落格式（set_paragraph_format)
• 设置页面边距（set_page_margins)
• 设置纸张大小和方向（set_page_size)

表格功能

• 生成表（create_table)
• 合并单元格（merge_table_cells)

插入对象

• 插入图像（insert_image)
• 插入图形（insert_shape)
• 插入超链接（insert_hyperlink)

管理文档结构

• 插入标题/脚注（insert_header_footer)
• 分享页面（insert_page_break)
• 创建目录（create_table_of_contents)
• 应用标题样式（apply_heading_style)

文本读取功能

• 阅读文档全文（get_text_all)
• 阅读特定页面文本（get_text_by_page)
• 阅读选中的文本（get_selected_text)
• 阅读特定段落文本（get_paragraph_text)
• 保存为文本文件（save_as_text)

🆕 高级分析和自动化功能

• 将表提取为CSV（get_table_as_csv）-以CSV格式提取/保存特定表格
• 戏剧性地改变（batch_replace）-一次替换多个文本
• 搜索文本（find_text）-搜索文本位置和周围内容
• 打开模板（fill_template）-用值填充占位符
• 文档结构分析（get_document_structure）-页面/段落/表格/图像/概述分析

精确位置控制（NEW！）

• 前往特定页面（move_to_page）-将光标移动到页码
• 前往特定文坛（move_to_paragraph_number）-将光标移动到段落编号
• 打开/关闭文档（move_to_document_start, move_to_document_end)

文本删除功能（NEW！）

• 删除选中的文本（delete_selected_text)
• 删除所有特定文本（delete_all_occurrences)
• 删除当前行（delete_current_line)
• 删除当前段落（delete_current_paragraph)
• 删除特定页面内容（delete_page_content)

保留和查看格式（NEW！

• 获取当前格式信息（get_current_char_shape）—查看字体、大小、颜色等
• 维持格式并插入文本（insert_text_preserving_format)

高级插入功能（NEW！）

• 在特定文本后面插入（insert_after_text）-添加到“标题”后面
• 插入到特定文本之前（insert_before_text）-添加到“标题”之前
• 添加到段落末尾（append_to_paragraph）-在第N个段落末尾
• 添加到文坛前（prepend_to_paragraph）-第N个段落前
• 插入到页面开始（insert_at_page_start)
• 插入到页面末尾（insert_at_page_end)

选择和更换（NEW！）

• 选择文坛（select_paragraph_by_number)
• 选择页面（select_page_content)
• 更新文坛内容（replace_paragraph）-将整个段落作为新文本

🚀 性能优化和自动化控制（NEW！）

• 控制屏幕更新（set_screen_updating）-提高批量操作的性能
• 自动化模式控制（set_automation_mode）-自动批准所有确认窗口
• 优化大量作业（optimize_for_bulk_operations）-最高性能模式
• 恢复正常模式（restore_normal_mode）-禁用优化

导出功能

• 导出PDF（export_to_pdf)
• 重置韩文（initialize_hwp)

📋 基本要求

系统要求

• 操作系统：Windows（韩文程序支持）
• python：3.10以上
• 韩文：韩文2010或更高版本（支持HWPFrame.HwpObject）

必需的软件包

pip install mcp fastmcp pywin32

🛠️ 安装和设置

1.安装软件包

# 필수 패키지 설치
pip install -r requirements.txt

# 또는 개별 설치
pip install mcp fastmcp pywin32

2.Claude桌面设置

在Claude Desktop的配置文件中添加以下内容：

Windows设置文件位置: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "advanced-hwp": {
      "command": "python",
      "args": [
        "D:/mcp/33MCP_HWP_Limone/advanced_hwp_server.py"
      ],
      "env": {
        "PYTHONPATH": "D:/mcp/33MCP_HWP_Limone"
      }
    }
  }
}

3.确认韩文程序安装

• 必须安装韩文程序
• COM对象注册必须正常

💡 推荐的工作流（重要！）

处理韩文文件时的必要步骤

根据Windows COM的特性， 运行多个韩文程序时，只连接到一个INS可以。 将以下步骤3工作流 必须遵循 运行稳定：

步骤1：确认正在运行的韩文文档

"현재 열려있는 한글 파일 목록을 보여줘"

→ list_all_hwp_windows() 呼叫 →确认所有运行中的韩文窗口、文件名和路径

输出示例:

실행 중인 한글 창 (2개):
  [0] !220324(보도자료)_주간아파트가격동향.hwp [C:\Users\...\Downloads\]
      PID: 27380, HWND: 12345
  [1] 회의록.hwp [D:\Documents\] - 한글
      PID: 28901, HWND: 67890

步骤2:确认并打开目标文档的完整路径

"아파트가격동향 파일을 열어줘"

→ open_document("C:\Users\...\아파트가격동향.hwp") 呼叫 →MCP实例打开该文件并将其转换为可控制状态 → 自动处理所有对话框 （版本警告、访问权限、密码等） → 韩文窗口在屏幕最前面 自动移动

重要:

• 不打开空文档 实际文件路径必须使用
• 文件路径使用步骤1中确定的路径

步骤3:执行文档操作

"'경기(-0.03%)'를 '[TEMP_GYEONGGI]'로 바꿔줘"
"문서 전체 내용을 읽어줘"

→ find_and_replace(), get_text_all() 使用 →立即运行所有确认窗口自动批准

📖 实际使用示例

用户：“现在打开的韩文文件中，请在公寓价格动向文件中将‘景气’改为‘GYEONGGI’。”

Claude自动执行顺序:

# 1단계
list_all_hwp_windows()
# → 출력: "!220324(보도자료)_주간아파트가격동향.hwp [C:\Users\LENOVO\Downloads\]"

# 2단계
open_document("C:\\Users\\LENOVO\\Downloads\\!220324(보도자료)_주간아파트가격동향.hwp")
# → "문서를 열었습니다" + 한글 창 최상단 표시

# 3단계
find_and_replace("경기", "GYEONGGI")
# → 자동으로 모든 '경기' 텍스트 바꾸기 (확인창 없음)

注意事项

🚀 自动化功能

所有确认对话框 自动批准可以：

• 版本警告对话框
• 确认文件访问权限
• 跳过密码输入
• 查找/替换确认窗口
• 删除确认窗口

此功能 initialize() 时自动激活，也可以手动控制。

🎯 使用方法

基本用法

Claude Desktop可以要求：

새 한글 문서를 만들고 "안녕하세요"라는 텍스트를 삽입해주세요.

高级使用

1.生成格式化文档

새 문서를 만들고 제목을 "보고서"로 하되 맑은고딕 18pt 굵게 설정하고, 
본문에 "내용입니다"를 바탕 12pt로 추가해주세요.

2.包含表格的文档

3행 4열 표를 만들고 첫 번째 행의 셀들을 병합해주세요.

3.插入图像

C:\images\logo.png 이미지를 문서에 삽입하고 크기를 100x50mm로 설정해주세요.

4.页面设置

A4 용지를 가로 방향으로 설정하고 여백을 상하좌우 15mm로 설정해주세요.

5.阅读文档内容

이 한글 문서를 열고 전체 내용을 읽어주세요.

6.阅读特定页面/段落

문서의 2페이지 내용만 읽어주세요.
첫 번째 문단의 내용을 확인해주세요.

7.转换为文本文件

이 한글 문서를 텍스트 파일로 저장해주세요.

8.连接正在运行的韩文

현재 열려있는 한글 문서 목록을 보여주세요.
아파트 가격 문서로 전환해주세요.

🆕 使用高级分析和自动化功能

9.将表格提取为CSV

문서의 첫 번째 표를 CSV로 추출해줘
두 번째 표를 C:\output\table.csv로 저장해줘

10.一次替换多个文本

다음 텍스트들을 한번에 바꿔줘: 주식회사->㈜, 2023년->2024년, 홍길동->김철수

11.搜索文本

문서에서 "세종"이 어디에 있는지 찾아줘
"아파트"라는 단어가 몇 번 나오는지 확인해줘

12.填充模板

문서의 {{이름}}을 홍길동으로, {{날짜}}를 2024-01-01로, {{금액}}을 1,000,000원으로 채워줘

13.文档结构分析

이 문서의 전체 구조를 분석해줘
문서에 표가 몇 개 있고 어떤 내용인지 알려줘

如何使用新编辑功能（故障排除！）

14.在正确的位置插入文本

3페이지로 이동해서 "새로운 내용"을 추가해줘
"서론" 뒤에 "이 문서는..."을 추가해줘
첫 번째 문단 끝에 "추가 설명"을 넣어줘

15.删除文本

"초안"이라는 단어를 모두 삭제해줘
현재 문단을 삭제해줘
2페이지의 모든 내용을 지워줘

16.保持格式并进行编辑

현재 위치의 서식 정보를 알려줘
서식을 유지하면서 "중요 내용"을 삽입해줘

17.高级插入（基于特定文本）

"1. 서론" 뒤에 줄바꿈하고 본문을 추가해줘
"제목" 앞에 "최종본 - "을 붙여줘
두 번째 "결론" 뒤에 추가 설명을 넣어줘  (nth_occurrence 사용)

18.编辑段落单位

0번째 문단을 "새로운 제목"으로 교체해줘
1번째 문단을 선택하고 서식을 적용해줘
2번째 문단 앞에 "중요: "를 추가해줘

🚀 使用性能优化（NEW！）

19.优化批量作业

대량 작업 최적화 모드를 켜줘
(1000개 텍스트를 일괄 바꾸기)
일반 모드로 복원해줘

20.手动优化控制

화면 업데이트를 꺼줘  (성능 향상)
(작업 수행)
화면 업데이트를 켜줘  (정상 속도)

21.自动化模式（确认窗口自动批准）

자동화 모드를 켜줘  (모든 확인창 자동 Yes)
(바꾸기, 삭제 등 작업 - 확인창 없이 즉시 실행)

💡 提示：初始化时自动启用自动化模式，因此即使不单独设置，也不会显示确认窗口！

📁 项目结构

33MCP_HWP_Limone/
├── advanced_hwp_server.py      # 메인 MCP 서버
├── requirements.txt            # 필수 패키지 목록
├── claude_desktop_config.json  # Claude Desktop 설정 예시
├── README.md                   # 이 파일
├── INSTALLATION_GUIDE.md       # 설치 가이드
└── hwp_mcp.log                 # 실행 로그

🔧 解决问题

1.韩文初始化失败

한글 프로그램이 설치되지 않았거나 초기화할 수 없습니다.

• 验证是否安装了韩文程序
• 运行一次韩文，确认是否正常运行
• 确认COM对象注册

2.软件包安装错误

pip install pywin32

• 以管理员权限运行
• 建议使用虚拟环境

3.Claude Desktop连接失败

• 验证设置文件路径是否正确
• 验证Python路径是否正确
• 检查防火墙设置

📊 功能摘要（共59项-新增24项！）

格式控制4字体、段落、页边空白、纸张 创建两个表格功能，合并单元格 |插入对象| 3个|图像、形状、超链接| |文档结构4标题/脚注，分页，目录，标题 |阅读文本5个|全部，分页，选择，段落，保存文本| |高级自动化| 5个CSV提取、批量更改、搜索、模板、结构分析| | 精确位置控制 | 4个（NEW） | 移动页面/段落，移动开始/结束 | | 删除文本 | 5个（NEW） | 删除选择、删除模式、删除行/段落/页面 | | 维持格式 | 2个（NEW） | 格式查询，插入格式保持 | | 高级插入 | 6个（NEW） | 插入文本前后，插入段落/页面位置 | | 选择和替换 | 3个（NEW） | 选择段落/页面，替换段落 | | 🚀 性能优化 | 4个（NEW） | 屏幕更新、自动化模式、批量任务优化 | |导出| 2个PDF，初始化|

🚧 已知限制

1. 仅Windows：韩文程序的特点是仅在Windows上运行
2. 韩文必修：必须安装韩文程序
3. COM依赖性：依赖Windows COM对象
4. 单实例连接：运行多个韩文时，COM只连接到一个进程

- list_all_hwp_windows()可以通过查看打开了哪些文件 - 控制其他进程中的文档的步骤 open_document()必须通过在MCP实例中打开该文件

📈 未来改进计划

• \[x\]添加文本读取功能（完成）
• \[x\]添加高级分析和自动化功能（完成）
• \[x\] 添加精确位置控制和删除功能（完成） ⭐
• \[x\] 添加格式保持和高级插入功能（完成） ⭐
• \[x\] 增强了文档打开的自动化（对话框自动处理，窗口顶部显示）（完成） ⭐
• \[\]添加宏执行功能
• \[\]添加图表插入功能
• \[\]增强的批量格式化功能
• \[\]优化性能
• \[\]改进错误处理

🤝 贡献

本项目旨在实现韩语文档操作的自动化。 欢迎您的贡献、反馈和问题报告！

GitHub: https://github.com/crowwan/hwp-mcp-advanced-custom.git

📄 许可证

该项目在MIT许可下分发。

______________________________________________________________________

💡 主要改进（v2.0）

已解决的问题

1. 定位疑难解答

- 现有：只能插入鼠标光标位置 - 改进：根据页码、段落编号和特定文本控制准确的位置

1. 完整实现删除功能

- 现有：没有删除函数 - 改进：5种删除方式（选择、模式、行、段落、页面）

1. 添加了维持格式的功能

- 现有：仅插入文本而不格式化 - 改进：查看和维护当前格式，并可插入

1. 高级插入功能

- 现有：仅插入当前位置 - 改进：精确插入“标题”前/后、第N个段落结束、页面开始/结束等

1. 提高打开文档的自动化程度

- 现有：需要手动处理对话框（版本警告、访问权限等） - 改进：自动批准所有确认对话框+自动显示韩文窗口

______________________________________________________________________

请参见：此MCP服务器合计数量 59个韩文控制功能提供，可以解决在工作中遇到的大多数文档编辑问题。