Hwp MCP

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

安装

uv pip install -e .

用法

运行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）

阅读（5）

写作（5）

格式化（3）

表（3）

高级（5）

光标和导航（11）

现场（12）

高级桌（11）

增强格式（5）

第页和第节（10）

图像与方程式（3）

表单控制（3）

文档信息（5）

打印和导出（3）

公用事业（4）

书签和超链接（6）

页眉/页脚和标题（2）

文档操作（8）

兼容性和设置（3）

控制与对象（4）

风格和脚本（4）

系统与安全（11）

H参数集操作（10）

项目结构

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

许可证

麻省理工学院