MCP server by mjyoo2
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
uv pip install -e .
Usage
Run MCP Server
python -m hwp_mcp.server
Claude Desktop Config
{
"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
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