Content
# HWP MCP Server
MCP (Model Context Protocol) server that enables LLMs to read and modify binary HWP (한글) documents via the HWP COM API.
## Architecture
```
LLM ↔ MCP Server (Python/FastMCP) ↔ PowerShell Bridge (JSON stdin/stdout) ↔ HWP COM API ↔ 한글
```
Python MCP server manages a long-running PowerShell subprocess that hosts HWP COM objects.
## Requirements
- **Windows** (HWP COM API is Windows-only)
- **한컴오피스 한글** installed (provides HWP COM server)
- **PowerShell 5.1+** (included with Windows)
- **Python >= 3.11**
## Installation
```bash
uv pip install -e .
```
## Usage
### Run MCP Server
```bash
python -m hwp_mcp.server
```
### Claude Desktop Config
```json
{
"mcpServers": {
"hwp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/hwp-mcp", "hwp-mcp"]
}
}
}
```
## MCP Tools (140)
> HWP COM API 199 HParameterSet 100% coverage
### Document Management (5)
| Tool | Description |
|------|-------------|
| `open_document` | Open HWP document |
| `close_document` | Close document |
| `list_open_documents` | List open documents |
| `save_document` | Save document |
| `save_document_as` | Save as different name/format |
### Read (5)
| Tool | Description |
|------|-------------|
| `get_document_text` | Extract full text |
| `get_paragraphs` | Get paragraph list |
| `get_tables` | Get table list |
| `get_table_data` | Get table data (2D array) |
| `search_text` | Search text |
### Write (5)
| Tool | Description |
|------|-------------|
| `replace_text` | Replace text |
| `insert_text` | Insert text |
| `set_table_cell_text` | Set table cell text |
| `append_paragraph` | Append paragraph |
| `set_text_file` | Set document content from text data |
### Formatting (3)
| Tool | Description |
|------|-------------|
| `set_text_style` | Character formatting (font, size, bold, color, etc.) |
| `set_paragraph_style` | Paragraph formatting (alignment, line spacing) |
| `set_page_style` | Page formatting (margins, orientation) |
### Table (3)
| Tool | Description |
|------|-------------|
| `create_table` | Create table |
| `add_table_row` | Add table row |
| `delete_table_row` | Delete table row |
### Advanced (5)
| Tool | Description |
|------|-------------|
| `run_hwp_action` | Execute arbitrary HWP action (power user) |
| `convert_to_hwpx` | Convert HWP → HWPX |
| `convert_to_pdf` | Convert HWP → PDF |
| `batch_convert_files` | Batch convert files (HWP, PDF, DOCX, etc.) |
| `set_file_security` | File security settings (copy/print restriction) |
### Cursor & Navigation (11)
| Tool | Description |
|------|-------------|
| `move_cursor` | Move cursor to specified position |
| `get_cursor_position` | Get current cursor position |
| `set_cursor_position` | Set cursor position (list, para, pos) |
| `get_pos_by_set` | Get cursor position as set |
| `set_pos_by_set` | Set cursor position from set |
| `get_selected_pos_by_set` | Get selection start/end positions |
| `select_text` | Select text range by coordinates |
| `get_selection_info` | Get current selection info |
| `clear_selection` | Clear selection |
| `delete_selection` | Delete selected content |
| `init_scan` | Initialize document scan |
### Field (12)
| Tool | Description |
|------|-------------|
| `create_field` | Create named field (template placeholder) |
| `field_exists` | Check if field exists |
| `get_field_list` | Get all field names |
| `get_field_text` | Read field text |
| `put_field_text` | Set field text |
| `get_current_field` | Get field name at cursor |
| `set_current_field_name` | Set current field name |
| `move_to_field` | Move cursor to field |
| `rename_field` | Rename field |
| `modify_field_properties` | Modify field properties |
| `set_field_ctrl_properties` | Set field control properties |
| `batch_fill_fields` | Batch fill multiple fields |
### Advanced Table (11)
| Tool | Description |
|------|-------------|
| `add_table_column` | Add table column |
| `delete_table_column` | Delete table column |
| `merge_table_cells` | Merge cells |
| `split_table_cell` | Split cell |
| `set_table_cell_style_adv` | Cell style (background, vertical alignment) |
| `set_table_border_adv` | Table border style |
| `table_to_text` | Table → text conversion |
| `text_to_table` | Text → table conversion |
| `swap_table_row_col` | Swap table rows/columns |
| `apply_table_template` | Apply table template |
### Enhanced Formatting (5)
| Tool | Description |
|------|-------------|
| `set_char_shape` | Extended character properties (kerning, spacing, shadow, etc.) |
| `set_bullet_style` | Bullet style |
| `set_numbering_style` | Numbering style |
| `set_tab_definition` | Tab stops |
| `manage_style` | Create/delete/apply styles |
### Page & Section (10)
| Tool | Description |
|------|-------------|
| `set_section_definition` | Section definition (binding margin, text flow) |
| `set_page_border` | Page border and background |
| `set_columns` | Multi-column layout |
| `set_page_number` | Page number |
| `set_header_footer` | Header/footer |
| `set_footnote_style` | Footnote style |
| `set_master_page` | Master page |
| `set_page_hiding` | Hide page elements (header/footer, etc.) |
| `set_page_num_ctrl` | Page number control (restart numbering) |
| `set_text_direction` | Text direction (horizontal/vertical) |
### Image & Equation (3)
| Tool | Description |
|------|-------------|
| `insert_picture` | Insert picture |
| `insert_background_picture` | Insert background picture |
| `create_equation` | Insert equation |
### Form Control (3)
| Tool | Description |
|------|-------------|
| `insert_form_control` | Insert form control (button, checkbox, etc.) |
| `set_form_properties` | Set form control properties |
| `get_form_data` | Read form data |
### Document Info (5)
| Tool | Description |
|------|-------------|
| `get_document_info` | Document metadata (page count, modified state) |
| `get_document_summary` | Document summary (title, author) |
| `get_page_text` | Extract specific page text |
| `get_page_count` | Total page count |
| `export_page_as_image` | Export page as image |
### Print & Export (3)
| Tool | Description |
|------|-------------|
| `print_document` | Print document |
| `set_watermark` | Set watermark (text/image) |
| `save_as_image` | Save document as image |
### Utility (4)
| Tool | Description |
|------|-------------|
| `convert_units` | Unit conversion (mm, pt, hwpunit) |
| `rgb_color` | RGB/Hex → HWP color value |
| `run_macro` | Run HWP macro |
| `get_file_info` | File metadata (without opening) |
### Bookmark & Hyperlink (6)
| Tool | Description |
|------|-------------|
| `insert_bookmark` | Insert bookmark |
| `insert_hyperlink` | Insert hyperlink |
| `hyperlink_jump` | Jump to hyperlink target |
| `insert_index_mark` | Insert index mark |
| `insert_auto_number` | Insert auto number field |
| `insert_cross_reference` | Insert cross reference |
### Header/Footer & Caption (2)
| Tool | Description |
|------|-------------|
| `set_drop_cap` | Drop cap (decorative first letter) |
| `set_caption` | Table/image caption |
### Document Operations (8)
| Tool | Description |
|------|-------------|
| `sort_text` | Sort text |
| `spell_check` | Spell check |
| `set_track_changes` | Track changes |
| `mail_merge` | Mail merge |
| `make_table_of_contents` | Generate table of contents |
| `insert_file` | Insert another file |
| `set_password` | Document password |
| `save_block` | Save selection to file |
### Compatibility & Settings (3)
| Tool | Description |
|------|-------------|
| `set_compatible_document` | Document compatibility mode |
| `set_view_properties` | HWP view properties (zoom, view mode, etc.) |
| `set_engine_properties` | HWP engine properties (spell check, auto-save, etc.) |
### Control & Object (4)
| Tool | Description |
|------|-------------|
| `delete_ctrl` | Delete selected control |
| `find_ctrl` | Find control |
| `check_x_object` | Check X object existence |
| `release_scan` | Release scan resources |
### Style & Script (4)
| Tool | Description |
|------|-------------|
| `import_style` | Import style |
| `export_style` | Export style |
| `run_script` | Run HWP script |
| `get_script_source` | Get script source |
### System & Security (11)
| Tool | Description |
|------|-------------|
| `register_module` | Register COM module |
| `set_drm_authority` | DRM authority |
| `lock_command` | Lock/unlock command |
| `is_command_lock` | Check command lock status |
| `set_message_box_mode` | Message box mode |
| `get_message_box_mode` | Get message box mode |
| `is_action_enable` | Check action enabled |
| `replace_action` | Replace action handler |
| `get_hwp_property` | Get HWP COM property |
| `set_hwp_property` | Set HWP COM property |
| `hwp_enum` | String → HWP enum value |
### HParameterSet Actions (10)
| Tool | Description | HParameterSet Count |
|------|-------------|---------------------|
| `hwp_table_param_action` | Table actions | 14 |
| `hwp_file_param_action` | File actions | 11 |
| `hwp_draw_param_action` | Draw object actions | 22 |
| `hwp_shape_param_action` | Shape actions | 6 |
| `hwp_style_param_action` | Style/border actions | 6 |
| `hwp_form_param_action` | Form actions | 13 |
| `hwp_doc_info_param_action` | Document info actions | 9 |
| `hwp_hanja_param_action` | Hanja/conversion actions | 11 |
| `hwp_selection_param_action` | Selection/position actions | 6 |
| `hwp_misc_param_action` | Miscellaneous actions | 69 |
## Project Structure
```
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
```
## Development
```bash
uv pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
```
## Limitations
- **Windows only**: HWP COM API requires Windows
- **한글 required**: 한컴오피스 한글 must be installed
- **Binary HWP only**: HWPX (XML-based) needs a separate server
## License
MIT
