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 个）

读取（5 个）

写入（5 个）

格式设置（3 个）

表格（3 个）

高级操作（5 个）

光标与导航（11 个）

字段（12 个）

高级表格（11 个）

增强格式设置（5 个）

页面与章节（10 个）

图像与公式（3 个）

表单控件（3 个）

文档信息（5 个）

打印与导出（3 个）

实用工具（4 个）

书签与超链接（6 个）

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

文档操作（8 个）

兼容性与设置（3 个）

控件与对象（4 个）

样式与脚本（4 个）

系统与安全（11 个）

HParameterSet 操作（10 个）

项目结构

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 文件需要单独的服务器。